Merge remote-tracking branch 'origin/master' into worktree/web-theme-settings-integration-fde706

# Conflicts: # docs/module-graph.md # packages/client/runtime/README.i18n.yaml # packages/client/runtime/tsconfig.json # packages/client/ui-conversation/README.i18n.yaml # packages/host/apiproxy/README.i18n.yaml
2026-08-08 16:56:49 +08:00
parent 27bb33e0f0 a44e35793c
commit 21c3bb1713
817 changed files with 13015 additions and 5418 deletions
--- a/packages/AGENTS.md
+++ b/packages/AGENTS.md
@@ -19,7 +19,7 @@ These package-specific rules supplement the repo-wide [conventions](../AGENTS.md

 Naming notes:

- **Package tsconfig shape:** extends `tsconfig.base.json` (client: `tsconfig.base.client.json`), `rootDir: src`, `outDir: lib/types`, a `references` entry per workspace dependency plus `support/invariants`; registered in exactly one aggregate — host packages in `tsconfig.host.json`, client in `tsconfig.client.json` ([layout](../docs/development.md#typescript-project-layout)).
+- **Package tsconfig:** extends `tsconfig.base.json` (Client: `tsconfig.base.client.json`), uses `rootDir: src`, `outDir: lib/types`, and references each workspace dependency plus `support/invariants`; registers in exactly one aggregate. Only `api/remotes` splits for generated contracts; ordinary two-entry Client plugins do not ([layout](../docs/development.md#typescript-project-layout)).
 - `src/types.ts` contains only types — no runtime code.
 - Tests live at package level under `tests/`, not `src/__tests__/`.
 - A package's README and JSDoc are part of the change: altered behavior (config keys, defaults, error codes, wire fields) updates them in the same commit. `doc-sync` gates what it can; apply [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for complete, concise prose and verify accuracy against code.
--- a/packages/api/remotes/README.i18n.yaml
+++ b/packages/api/remotes/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # 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: 7f6a2114d900413d972584c0f1c141b7f835ba36
-README.zh.md: cce263747d696570f362811556fa6f5c0be0a0f5
+README.md: 3d9de0955faefe37c95ff8bb792d57c4fa1f1a3a
+README.zh.md: 7490d68781d3a7b0002b73fe06056ec86c144575
--- a/packages/api/remotes/README.md
+++ b/packages/api/remotes/README.md
@@ -10,6 +10,14 @@ The current Client assembly mounts only the Goal Remote contribution. Cordis eff

 This package contains no transport or Host service discovery logic. Its Client face can be reused by Web or a future TUI that provides the same React-free `ctx.remote` contract.

+## Build boundary
+
+An ordinary repository package belongs to one TypeScript face: Host packages are registered in the root `tsconfig.host.json`, and Client packages in the root `tsconfig.client.json`. `api-remotes` is the only deliberate exception because its Host entry must participate in the Host TypeRT graph, while `src/client/index.ts` cannot compile until Host tsdown has generated the business packages' `/remote` declarations.
+
+This package's root `tsconfig.json` is only a solution that references `tsconfig.host.json` and `tsconfig.client.json`. The Host aggregate and direct Host consumers reference the former, while the Client aggregate and direct Client consumers reference the latter; the package-root solution must not enter either aggregate's dependency graph. The two projects own disjoint source files and `.tsbuildinfo` files but share the `lib/types` output directory.
+
+The package-local `clientBundle(..., { hostPhase: true })` makes Host tsdown bundle the Host entry and the later Client tsdown bundle only the browser entry. Ordinary Client plugins remain single Client projects and produce both their Node loader entry and browser bundle during Client tsdown; do not copy this package's split merely because a package has both `src/index.ts` and `src/client/index.ts`.
+
 ## Model Experience

 None, as this BFF selects Remote application methods and identity policy but registers no model surface.
--- a/packages/api/remotes/README.zh.md
+++ b/packages/api/remotes/README.zh.md
@@ -10,6 +10,14 @@

 本包不包含传输逻辑或 Host 服务发现逻辑。Web 或未来的 TUI 只要提供同一份不依赖 React 的 `ctx.remote` 契约，均可复用其 Client face。

+## 构建边界
+
+仓库中的普通包只属于一个 TypeScript face：Host 包登记在根 `tsconfig.host.json`，Client 包登记在根 `tsconfig.client.json`。`api-remotes` 是唯一刻意拆分的特例，因为它的 Host 入口要参与 Host TypeRT 图，而 `src/client/index.ts` 必须等 Host tsdown 生成业务包的 `/remote` 声明后才能编译。
+
+本包根 `tsconfig.json` 只是引用 `tsconfig.host.json` 与 `tsconfig.client.json` 的 solution。Host aggregate 和 Host 直接消费方引用前者，Client aggregate 和 Client 直接消费方引用后者；禁止把包根 solution 放进任一 aggregate 的依赖图。两个 project 拥有互不重叠的源码和 `.tsbuildinfo`，但共享 `lib/types` 输出目录。
+
+包内 `clientBundle(..., { hostPhase: true })` 让 Host tsdown 打包 Host 入口，让后续 Client tsdown 只打包 browser 入口。普通 Client 插件仍使用单一 Client project，并在 Client tsdown 阶段一起生成 Node loader 入口和 browser bundle；不得因一个包同时存在 `src/index.ts` 与 `src/client/index.ts` 就复制本包的拆分。
+
 ## 模型体验

 无，因为该 BFF 只选择 Remote 应用方法和身份策略，不注册任何模型接口。
--- a/packages/api/remotes/tsconfig.client.json
+++ b/packages/api/remotes/tsconfig.client.json
@@ -0,0 +1,22 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "tsBuildInfoFile": "lib/tsconfig.client.tsbuildinfo"
+  },
+  "files": [
+    "src/client/index.ts"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../goal/goal"
+    },
+    {
+      "path": "../../typert/type-meta"
+    }
+  ]
+}
--- a/packages/api/remotes/tsconfig.host.json
+++ b/packages/api/remotes/tsconfig.host.json
@@ -0,0 +1,36 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "tsBuildInfoFile": "lib/tsconfig.host.tsbuildinfo"
+  },
+  "files": [
+    "src/agent-lookup.ts",
+    "src/index.ts",
+    "src/invariant.ts"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../session-persistence/session-persistence"
+    },
+    {
+      "path": "../../support/invariants"
+    },
+    {
+      "path": "../../typert/registry"
+    },
+    {
+      "path": "../../typert/type-meta"
+    }
+  ]
+}
--- a/packages/api/remotes/tsconfig.json
+++ b/packages/api/remotes/tsconfig.json
@@ -1,42 +1,11 @@
 {
-  "extends": "../../../tsconfig.base.client.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "lib/types"
-  },
-  "include": [
-    "src"
-  ],
+  "files": [],
  "references": [
    {
-      "path": "../../../vendor/cordis"
+      "path": "./tsconfig.host.json"
    },
    {
-      "path": "../../core/agent"
-    },
-    {
-      "path": "../../core/session"
-    },
-    {
-      "path": "../../session-persistence/session-persistence"
-    },
-    {
-      "path": "../../typert/type-meta"
-    },
-    {
-      "path": "../../typert/registry"
-    },
-    {
-      "path": "../../ui/commands"
-    },
-    {
-      "path": "../../goal/goal"
-    },
-    {
-      "path": "../../session-title/session-title"
-    },
-    {
-      "path": "../../support/invariants"
+      "path": "./tsconfig.client.json"
    }
  ]
 }
--- a/packages/api/remotes/tsdown.config.ts
+++ b/packages/api/remotes/tsdown.config.ts
@@ -1,3 +1,7 @@
 import { clientBundle } from '../../client/tsdown.client.ts'

-export default clientBundle('@deepseek-ai/dsh-api-remotes', ['lib/types/index.js', 'lib/types/invariant.js'])
+export default clientBundle(
+  '@deepseek-ai/dsh-api-remotes',
+  ['lib/types/index.js', 'lib/types/invariant.js'],
+  { hostPhase: true },
+)
--- a/packages/bash/bash-sandbox/package.json
+++ b/packages/bash/bash-sandbox/package.json
@@ -41,6 +41,6 @@
    "@deepseek-ai/dsh-sandbox-local": "workspace:^",
    "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
    "cordis": "^4.0.0-rc.7",
-    "node-addon-landlock-run": "0.0.0-test.0"
+    "@deepseek-ai/node-addon-landlock-run": "workspace:*"
  }
 }
--- a/packages/bash/bash-sandbox/tests/landlock.e2e.ts
+++ b/packages/bash/bash-sandbox/tests/landlock.e2e.ts
@@ -5,7 +5,7 @@ import { homedir, tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import { launcherPath } from 'node-addon-landlock-run'
+import { launcherPath } from '@deepseek-ai/node-addon-landlock-run'
 import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
 import { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
 import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
@@ -13,14 +13,14 @@ import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'

 /**
 * KEYLESS consumer-integration proof: the REAL `LocalSandboxProvider` (bwrap
- * rung forced off, so the npm-distributed `landlock-run` confines) underneath the
+ * rung forced off, so the workspace `landlock-run` launcher confines) underneath the
 * REAL `SandboxBashExecutor`, driven through the executor's public run/start
 * paths. Verifies the WORLD (files exist or don't) plus the stamped result
 * facts; the backend-only confinement proofs live with
 * `@deepseek-ai/dsh-sandbox-local`.
 *
- * Self-skips when the running kernel does not enforce Landlock; the
- * launcher binary itself arrives with `pnpm install` (`node-addon-landlock-run`).
+ * Self-skips when the running kernel does not enforce Landlock. CI builds the launcher from
+ * `native/landlock-run` before running this file.
 */

 const probe = spawnSync(launcherPath(), ['--probe'], { timeout: 5_000, encoding: 'utf8' })
--- a/packages/bash/bash-sandbox/tests/partial-landlock.spec.ts
+++ b/packages/bash/bash-sandbox/tests/partial-landlock.spec.ts
@@ -9,7 +9,7 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import { LAUNCHER_FAILURE_EXIT } from 'node-addon-landlock-run'
+import { LAUNCHER_FAILURE_EXIT } from '@deepseek-ai/node-addon-landlock-run'
 import { SANDBOX_UNAVAILABLE, SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
 import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
 import { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
--- a/packages/bash/bash-sandbox/tsconfig.json
+++ b/packages/bash/bash-sandbox/tsconfig.json
@@ -14,6 +14,9 @@
    {
      "path": "../../../vendor/cordis"
    },
+    {
+      "path": "../../../native/landlock-run/packages/entry"
+    },
    {
      "path": "../../util/brand"
    },
--- a/packages/bundle/base/cordis.patch.yml
+++ b/packages/bundle/base/cordis.patch.yml
@@ -77,12 +77,10 @@
    - id: settings
      name: '@deepseek-ai/dsh-settings-local'

-    # Credential store: the live process environment over `$DSH_HOME/.env`
-    # (owner-only file, hot-reloaded). Adapters resolve their key references
-    # through it at each request, so no key is inlined in this file. The web
-    # Models page's key inputs write it through `credentials.set`; nothing hoists
-    # the document into the process environment, which would make every stored key
-    # read as an unrotatable ambient override.
+    # Credential sources: inherited environment over the managed
+    # `$DSH_HOME/.credentials.yaml`, with project and user `.env` fallbacks.
+    # Adapters resolve references per request; the Models page writes only the
+    # managed document, which is never materialized into the process environment.
    - id: credentials
      name: '@deepseek-ai/dsh-credentials-local'

@@ -220,6 +218,10 @@
    - id: skill-local
      name: '@deepseek-ai/dsh-skill-local'

+    - id: skill-badge
+      name: '@deepseek-ai/dsh-skill-badge'
+      disabled: true
+
    - id: tool-skill
      name: '@deepseek-ai/dsh-tool-skill'

@@ -382,7 +384,6 @@
      name: '@deepseek-ai/dsh-web-search-deepseek'
      config:
        apiKeyEnv: DEEPSEEK_API_KEY
-        baseURL: !!js process.env.DEEPSEEK_SEARCH_BASE_URL

    - id: tool-web
      name: '@deepseek-ai/dsh-tool-web'
--- a/packages/bundle/base/package.json
+++ b/packages/bundle/base/package.json
@@ -70,6 +70,7 @@
    "@deepseek-ai/dsh-session-title-first-message-llm": "workspace:^",
    "@deepseek-ai/dsh-settings-local": "workspace:^",
    "@deepseek-ai/dsh-skill": "workspace:^",
+    "@deepseek-ai/dsh-skill-badge": "workspace:^",
    "@deepseek-ai/dsh-skill-local": "workspace:^",
    "@deepseek-ai/dsh-spill-local": "workspace:^",
    "@deepseek-ai/dsh-spill-policy": "workspace:^",
--- a/packages/bundle/base/tests/fixtures/root.cordis.yml
+++ b/packages/bundle/base/tests/fixtures/root.cordis.yml
@@ -0,0 +1 @@
+[]
--- 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: d08fb08e2aca3c4e5ccd733b37fc415d492974ca
-README.zh.md: 99a64ef04c4fd8fb0c6a979d3f09f1bd98b434a0
+README.md: 661b377817482d22f58f22b573075722646729a2
+README.zh.md: a6b91a8e60fdcc06ba23e07dcb2f4208ea1020f7
--- a/packages/bundle/headless/README.md
+++ b/packages/bundle/headless/README.md
@@ -2,7 +2,7 @@

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

-The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md) + [`dsh-web-app`](../web-app/README.md): it moves the webserver to an OS-assigned port (parallel runs never collide), silences the URL line, and inserts this package's `headless-runner` plugin (config `{task}`). The runner drives one task turn through the in-process API carrier (`InProcessApiClient` over `toFetchHandler(ctx.apiProxy)`, so the full wire chain — serialization, zod, SSE framing — really runs), aggregates the turn's final assistant text, writes it to stdout, and requests exit (completed → 0, else 1) through the launcher-provided `ctx.headlessIo` seam. The Web composition stays mounted, so the running session is observable in a browser at the stderr-announced URL. The launcher patches the task text in (`dsh --profile headless "task"`), and fails loud when a task is given to a profile without this row.
+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.

 ## Model Experience

--- a/packages/bundle/headless/README.zh.md
+++ b/packages/bundle/headless/README.zh.md
@@ -2,7 +2,7 @@

 [English](README.md) | 中文

-dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) + [`dsh-web-app`](../web-app/README.md) 之上：把 webserver 移到 OS 分配的端口（并行运行绝不冲突），关闭 URL 行输出，并插入本包的 `headless-runner` 插件（配置为 `{task}`）。runner 通过进程内 API 载体（架在 `toFetchHandler(ctx.apiProxy)` 之上的 `InProcessApiClient`，因此序列化、zod、SSE（Server-Sent Events）帧封装这整条 wire 链路都会真实运行）驱动一个任务轮次，聚合该轮次最终的 assistant 文本，写到 stdout，再经启动器提供的 `ctx.headlessIo` seam 请求退出（完成 → 0，否则 1）。Web 组合保持挂载，因此运行中的会话可在浏览器中通过 stderr 公告的 URL 观察。启动器把任务文本 patch 进来（`dsh --profile headless "task"`）；如果向没有这一行的 profile 传入任务，则大声失败。
+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 缺少该行，则显式报错。

 ## 模型体验

--- a/packages/bundle/headless/src/index.ts
+++ b/packages/bundle/headless/src/index.ts
@@ -6,8 +6,7 @@
 * (InProcessApiClient over toFetchHandler(ctx.apiProxy), so the full wire
 * chain — serialization, zod, SSE framing — really runs), prints the final
 * assistant text at agent quiescence, and exits (completed → 0, else 1). The
- * task text arrives as launcher-patched config
- * (`dsh --profile headless "task"`).
+ * task text arrives as launcher-patched config (`dsh run "task"`).
 * @module @deepseek-ai/dsh-headless
 */

@@ -86,26 +85,31 @@ async function unwrap<T>(response: RpcResponse<T>, io: HeadlessIo): Promise<T> {
 * `agent/status` subscription; the stream itself carries no status frame.
 * @param frames - the mux stream opened before the prompt.
 * @param sessionId - the headless session.
- * @param idle - resolves when the agent reaches quiescence.
+ * @param 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<void>,
+  idle: Promise<number>,
  io: HeadlessIo,
 ): Promise<TurnOutcome> {
  let started = false
  let text = ''
  let reason: string = 'error'
-  void (async () => {
+  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
@@ -121,7 +125,12 @@ async function consumeUntilIdle(
      io.stderr.write(`dsh: event stream failed: ${String(error)}\n`)
    }
  })()
-  await idle
+  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
+  }
  return { text, reason }
 }

@@ -154,9 +163,9 @@ export function apply(ctx: Context, config: Config): void {
    // port of this runner must replace it with a wire-visible idle signal.
    const abort = new AbortController()
    const frames = api.events.mux({}, abort.signal)
-    const idle = new Promise<void>((resolve) => {
+    const idle = new Promise<number>((resolve) => {
      ctx.on('agent/status', ({ agent, status }) => {
-        if (agent.id === created.sessionId && status === 'idle') resolve()
+        if (agent.id === created.sessionId && status === 'idle') resolve(agent.session.seq - 1)
      })
    })
    const done = consumeUntilIdle(frames, created.sessionId, idle, io)
--- a/packages/bundle/headless/tests/headless.spec.ts
+++ b/packages/bundle/headless/tests/headless.spec.ts
@@ -21,26 +21,45 @@ function stamped(event: ScriptedEvent): ScriptedEvent {

 interface RpcShapedRequest { rpcId: string }

+interface ScriptedApiOptions {
+  promptFails?: boolean
+  framesAfterPrompt?: boolean
+  onPrompt?: () => void
+}
+
 /** Build a fake apiProxy (echoing rpcIds like the real gateway) whose mux stream replays `events` for the created session. */
-function scriptedApi(events: ScriptedEvent[], options: { promptFails?: boolean } = {}): unknown {
+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
+  })
  return {
    sessions: {
      create: (request: RpcShapedRequest) =>
        Promise.resolve({ rpcId: request.rpcId, result: { ok: true, value: { sessionId: 'S1' } } }),
-      prompt: (request: RpcShapedRequest) => Promise.resolve(options.promptFails === true
-        // A code from the closed wire union: the carrier schema rejects invented codes.
-        ? { rpcId: request.rpcId, result: { ok: false, error: { code: 'agent-busy', message: 'agent is busy', details: { reason: 'test' } } } }
-        : { rpcId: request.rpcId, result: { ok: true, value: { accepted: true } } }),
+      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* () {
-        for (const event of events) {
-          if (event.type === 'stream/error') {
+        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
          }
-          const { sessionId = 'S1', ...rest } = event
-          yield { rpcId: 'e', payload: { type: 'session/event', sessionId, event: stamped(rest) } }
+          yield { rpcId: 'e', payload: { type: 'session/event', sessionId: item.sessionId, event: item.event } }
        }
      },
    },
@@ -51,7 +70,10 @@ function scriptedApi(events: ScriptedEvent[], options: { promptFails?: boolean }
 * Mount the runner against a scripted API, emit the idle transition after the
 * scripted frames drain, and wait for its exit request.
 */
-async function run(events: ScriptedEvent[], options: { promptFails?: boolean } = {}): Promise<{ code: number; out: string; err: string }> {
+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 = ''
@@ -63,16 +85,25 @@ async function run(events: ScriptedEvent[], options: { promptFails?: boolean } =
    }
    ctx.provide('headlessIo', io)
  })
-  ctx.provide('apiProxy', scriptedApi(events, options) as never)
+  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.
-  await new Promise(resolve => setTimeout(resolve, 10))
-  ctx.emit('agent/status', { agent: { id: 'OTHER' } as Agent, status: 'idle' })
-  ctx.emit('agent/status', { agent: { id: 'S1' } as Agent, status: 'running' })
-  ctx.emit('agent/status', { agent: { id: 'S1' } as Agent, status: 'idle' })
+  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 }
@@ -106,6 +137,15 @@ describe('headless runner', () => {
    expect(err).toContain('observing at http://127.0.0.1:12345')
  })

+  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('exits 1 when the final turn ends for any other reason', async () => {
    const { code } = await run([messageTurn, end(1, 'aborted')])
    expect(code).toBe(1)
@@ -168,7 +208,7 @@ describe('headless runner', () => {
    ctx.provide('httpServer', { port: 1 } as never)
    apply(ctx, { task: 't' })
    await new Promise(resolve => setTimeout(resolve, 10))
-    ctx.emit('agent/status', { agent: { id: 'S1' } as Agent, status: 'idle' })
+    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')
    await ctx.fiber.dispose()
--- a/packages/bundle/web-app/cordis.patch.yml
+++ b/packages/bundle/web-app/cordis.patch.yml
@@ -35,11 +35,6 @@
    # once the web UI owns the choice per session.
    mode: !!js process.env.DSH_TOOLS_MODE

- id: llm-deepseek
-  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-    baseURL: !!js process.env.DEEPSEEK_BASE_URL
-
 # ── web-only host rows, the transport layer, and the browser roster ─────────

 # `dshClient` rows are the browser roster the modules node half scans into
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -2449,7 +2449,8 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
        if (missing !== undefined) return missing
        return ok(request, {
          skills: [
-            { name: 'fixture-demo', description: 'fixture 技能样本', whenToUse: '仅供 UI 目录渲染验收' },
+            { name: 'fixture-demo', description: 'fixture 技能样本', whenToUse: '仅供 UI 目录渲染验收', modelInvocable: true },
+            { name: 'fixture-user-only', description: 'fixture 仅用户技能样本', modelInvocable: false },
          ],
        })
      },
--- a/packages/client/connection/tests/fake-api.ts
+++ b/packages/client/connection/tests/fake-api.ts
@@ -163,6 +163,7 @@ export class FakeApiClient implements IApiClient {
  onSkillList: (payload: unknown) => Promise<RpcResponse<{ skills: SkillEntry[] }>>
    = () => Promise.resolve(ok({ skills: [] }))

+
  readonly commands: IApiClient['commands'] = {
    list: (payload: unknown) => this.record('command.list', payload, this.onCommandList(payload)),
    execute: (payload: unknown) => this.record('command.execute', payload, this.onCommandExecute(payload)),
--- 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: 767352a0682f16abcbfce3c226cda790adcc8011
-README.zh.md: 791a74691cd20705614ac782d6b55d9af290955c
+README.md: 8b96ef38c67e4548b3a7d274d8154509ad1a24c2
+README.zh.md: a9e8e54f2e86e098b6e3fb41ddaae800bfa465cf
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -24,6 +24,8 @@ Workspace and Session lists have independent monotone `pending` → `ready` base

 SlotsService gives the renderer separate bare observables for `useSessions` and `useWorkspaces`; web-react creates the hooks. Workspace business state does not enter `SessionListState` or an entry store.

+`indexSubagentDescendants()` derives per-parent total and running descendant counts from the retained list mirror. It follows only uninterrupted `origin: 'subagent'` ancestry, so an ordinary fork starts a separate ownership subtree; cycles stop without throwing, and a missing parent remains a harmless key until its summary arrives.
+
 `SessionsService.search(query, signal)` is a stateless one-shot action over the `session.search` RPC. It returns ranked session/snippet pairs without putting query, loading, or error state into the shared Session list, so each UI owner controls debounce, cancellation, stale-response suppression, and fallback presentation. `searchResultLimit` re-exposes `SESSION_SEARCH_RESULT_LIMIT` — the bound the response schema itself enforces — as injected presentation data, so client plugins do not duplicate it. It is a protocol constant rather than per-connection state, so the connection handle does not carry it.

 ## New Session and the blank mirror
@@ -38,7 +40,7 @@ SlotsService gives the renderer separate bare observables for `useSessions` and

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

-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 comes from the checkpoint's `compact/summary` provenance; a window cut that left the provenance outside makes the row non-expandable rather than empty, and a later page that supplies it resolves the text. 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 `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.

 ## Request inspection

--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -24,6 +24,8 @@ Workspace 和 Session 列表各自具有单调的 `pending` → `ready` 基线

 SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸 observable；web-react 创建钩子。Workspace 业务状态不会进入 `SessionListState` 或配置项 store。

+`indexSubagentDescendants()` 从保留的列表镜像中派生每个 parent 的后代总数与运行中后代数。它只沿不间断的 `origin: 'subagent'` 祖先链追踪，因此普通 fork 会开启独立的归属子树；遇到环时，追踪会停止但不会抛出异常，缺失的 parent 则会保留为无害的键，直至其摘要到达。
+
 `SessionsService.search(query, signal)` 是基于 `session.search` RPC 的无状态单次操作。它返回经过排序的会话／snippet 对，但不会将查询条件、加载状态或错误状态写入共享 Session 列表，因此每个 UI 所有者都自行负责防抖、取消、抑制陈旧响应和回退呈现。`searchResultLimit` 将 `SESSION_SEARCH_RESULT_LIMIT`——即响应 schema 自身强制执行的上限——作为注入的呈现数据重新公开，使客户端插件无需复制该值。它是协议常量而非逐连接状态，因此连接 handle 不携带它。

 ## New Session 与 blank 镜像
@@ -38,7 +40,7 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸

 `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 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本来自检查点的 `compact/summary` 溯源；窗口切分把溯源留在窗口外时该行不可展开而非空白，后续补上溯源的分页会解析出文本。性能契约：一次追加最多物化一个节点，并且仅在加入该节点时复制投影；不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。
+由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本、被替换条目数量和估算的被遮蔽 token 数量都来自检查点的 `compact/summary` 溯源；窗口切分把溯源留在窗口外时这些字段不可用，后续补上溯源的分页会解析出它们。`CommandNode.outcome.sourceEventSeq` 保留成功命令对该摘要事件的显式引用，使呈现层能够配对 `/compact` 与其检查点，而无须解析结算文案或假定两行相邻。性能契约：一次追加最多物化一个节点，并且仅在加入该节点时复制投影；不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。

 ## 请求检查

--- a/packages/client/runtime/package.json
+++ b/packages/client/runtime/package.json
@@ -25,7 +25,6 @@
  "dshClient": {
    "inject": [
      "@deepseek-ai/dsh-client-connection",
-      "@deepseek-ai/dsh-api-remotes",
      "@deepseek-ai/dsh-typert-registry"
    ],
    "platform": "web",
@@ -50,14 +49,12 @@
  },
  "peerDependencies": {
    "@deepseek-ai/dsh-invariants": "^0.0.1",
-    "@deepseek-ai/dsh-api-remotes": "^0.0.1",
    "@deepseek-ai/dsh-type-meta": "^0.0.1",
    "@deepseek-ai/dsh-typert-registry": "^0.0.1",
    "cordis": "^4.0.0-rc.7"
  },
  "devDependencies": {
    "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@deepseek-ai/dsh-api-remotes": "workspace:^",
    "@deepseek-ai/dsh-timeout": "workspace:^",
    "@deepseek-ai/dsh-type-meta": "workspace:^",
    "@deepseek-ai/dsh-typert-registry": "workspace:^",
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -1,7 +1,6 @@
 /** Browser runtime services for slots, sessions, workspaces, and connection-stream delivery. */
 import type { Context } from 'cordis'
 import type { ConnectionHandle, SessionId } from '@deepseek-ai/dsh-client-connection/client'
-import type {} from '@deepseek-ai/dsh-api-remotes/client'
 import type { TypeRTContext } from '@deepseek-ai/dsh-type-meta'
 import type { MaybeSnapshotSelectorHook, SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotsService } from './slots.ts'
@@ -16,6 +15,8 @@ export { SlotsService } from './slots.ts'
 export type { RootOwnerProps } from './slots.ts'
 export { SessionCreateError, SessionsService, scopeOf, workspaceTitleOf } from './sessions/service.ts'
 export { SessionHistoryService } from './session-history/service.ts'
+export { indexSubagentDescendants } from './sessions/subagent-lineage.ts'
+export type { SubagentDescendantSummary } from './sessions/subagent-lineage.ts'
 // The provide channel is shared with the client test runtime (one
 // materialization/projection implementation; no test-side mirror to drift).
 export { SessionProvideChannel } from './sessions/provide.ts'
@@ -181,8 +182,8 @@ declare module 'cordis' {
  }
 }

-/** Required services: the Remote root, wire handle, and Client TypeRT registry. */
-export const inject = ['remote', 'connection', 'typert']
+/** Required services: the wire handle and Client TypeRT registry. */
+export const inject = ['connection', 'typert']

 /** Mounts the browser runtime services and connection stream.
 * @param ctx - Client Cordis context.
--- a/packages/client/runtime/src/client/sessions/context-provenance.ts
+++ b/packages/client/runtime/src/client/sessions/context-provenance.ts
@@ -83,6 +83,9 @@ export function contextProvenance(source: unknown): ContextProvenanceView {
      return { role: 'inject', label: joined(collect(record, 'changes', 'path')) ?? kind }
    case 'plugin':
      return { role: 'inject', label: readString(record, 'plugin') ?? kind }
+    // A user-explicit skill invocation names the skill it injected.
+    case 'skill-invocation':
+      return { role: 'inject', label: readString(record, 'name') ?? kind }
    // Documented default arm of the merge-extensible source map: an unknown
    // producer still identifies itself by its own durable kind.
    default:
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -192,6 +192,12 @@ export interface CompactionSummaryNode {
  /** 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: string | null
+  /** Seq of the loaded `compact/summary` event, or null when that provenance is outside the window. */
+  summaryEventSeq: number | null
+  /** Number of surface items replaced, or null when summary provenance is unavailable or malformed. */
+  shadowedItemCount: number | null
+  /** Estimated token price of the replaced items, or null when summary provenance is unavailable or malformed. */
+  shadowedTokenCount: number | null
 }

 /**
@@ -236,7 +242,12 @@ export interface CommandNode {
   */
  args: string | null
  /** Settlement outcome (done payload); null while the command is still executing. */
-  outcome: { kind: 'success' | 'error'; text?: string } | null
+  outcome: {
+    kind: 'success' | 'error'
+    text?: string
+    /** Earlier authoritative domain event for a richer client-computed presentation. */
+    sourceEventSeq?: number
+  } | null
 }

 /** Finalized conversation node union (kind discriminates; seq is the React key). */
--- a/packages/client/runtime/src/client/sessions/subagent-lineage.ts
+++ b/packages/client/runtime/src/client/sessions/subagent-lineage.ts
@@ -0,0 +1,50 @@
+/**
+ * Pure subagent-lineage aggregation over the retained session-list mirror.
+ * Ordinary forks terminate propagation so each visible session owns only its
+ * uninterrupted subagent subtree.
+ * @module @deepseek-ai/dsh-client-runtime/client/sessions/subagent-lineage
+ */
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import type { SessionSummary } from './service.ts'
+
+/** Descendant counts projected for one possible parent session. */
+export interface SubagentDescendantSummary {
+  /** All descendants connected through uninterrupted subagent-origin lineage. */
+  readonly count: number
+  /** Descendants whose exact session summary is currently running. */
+  readonly runningCount: number
+}
+
+/**
+ * Index every subagent descendant under each ancestor it reaches through an
+ * uninterrupted subagent-origin chain. Cycles fail soft and orphan owners
+ * remain harmless map keys until their summaries arrive.
+ * @param summaries - retained session summaries keyed by id.
+ * @returns descendant totals and running totals keyed by possible parent id.
+ */
+export function indexSubagentDescendants(
+  summaries: Readonly<Record<SessionId, SessionSummary>>,
+): ReadonlyMap<SessionId, SubagentDescendantSummary> {
+  const indexed = new Map<SessionId, { count: number; runningCount: number }>()
+  for (const descendant of Object.values(summaries)) {
+    if (descendant.origin !== 'subagent') continue
+    const seen = new Set<SessionId>()
+    let current: SessionSummary | undefined = descendant
+    while (current?.origin === 'subagent' && current.parentId !== undefined
+      && !seen.has(current.id)) {
+      seen.add(current.id)
+      const aggregate = indexed.get(current.parentId)
+      if (aggregate === undefined) {
+        indexed.set(current.parentId, {
+          count: 1,
+          runningCount: descendant.running ? 1 : 0,
+        })
+      } else {
+        aggregate.count += 1
+        if (descendant.running) aggregate.runningCount += 1
+      }
+      current = summaries[current.parentId]
+    }
+  }
+  return indexed
+}
--- a/packages/client/runtime/src/client/sessions/transcript-adapter.ts
+++ b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
@@ -57,10 +57,11 @@ function materializeNode(
  stepTimings: ReadonlyMap<string, AssistantStepMetadata>,
 ): ConversationNode {
  switch (event.type) {
-    case 'user/message':
-      // Injected context (plugin/goal 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).
+    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,
@@ -80,6 +81,7 @@ function materializeNode(
        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,
@@ -156,6 +158,29 @@ function compactSummaryText(event: SessionEvent): string | null {
  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 own provenance (`sourceEventSeqs` names the
@@ -170,13 +195,28 @@ function materializeCompaction(
 ): 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
-    summary = compactSummaryText(candidate)
+    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 }
+  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). */
@@ -321,9 +361,22 @@ export class TranscriptAdapter {
      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 }
+    const data = event.data as unknown as {
+      commandId: CommandId
+      kind: 'success' | 'error'
+      text?: string
+      sourceEventSeq?: number
+    }
    const run = this.commandIdx.get(data.commandId)
-    const outcome = { kind: data.kind, ...data.text === undefined ? {} : { text: data.text } }
+    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).
--- a/packages/client/runtime/src/client/slots.ts
+++ b/packages/client/runtime/src/client/slots.ts
@@ -19,7 +19,7 @@ import type { Context } from 'cordis'
 import { SlotCore } from '@deepseek-ai/dsh-client-ui-slots'
 import type {
  LocaleFace, OwnerOf, SlotEntryDef, SlotMap, SlotRenderer, SlotRendererHost,
-  SlotScope, SlotSpec, StoreDecl, StoredEntry, StoreInstanceLike,
+  SlotScope, SlotSpec, StoreDecl, StoreFactory, StoredEntry, StoreInstanceLike,
 } from '@deepseek-ai/dsh-client-ui-slots'

 declare module '@deepseek-ai/dsh-client-ui-slots' {
@@ -35,16 +35,11 @@ export interface RootOwnerProps { children?: never }
 /** Instance key for root-scoped store records (session records key by session id, so the literal cannot collide). */
 const ROOT_INSTANCE_KEY = 'root'

-// FIXME(slot-parity): the engine's arbitrated persist extensions — create()
-// takes the scope key (per-session localStorage suffix) and instances expose
-// clearPersisted() — are not yet on ui-slots' StoreHandle/StoreInstanceLike;
-// these local structural faces bridge until fw-slots lifts them.
+/** Canonical type-erased store handle used by the runtime lifecycle map. */
+type EngineStoreHandle = Exclude<StoreDecl, StoreFactory>

-/** Store handle face as the engine actually ships it (scope-key-aware create). */
-interface EngineStoreHandle { create(scopeKey?: string): EngineStoreInstance }
-
-/** Engine instance face: the host-contract shape plus persisted-state cleanup. */
-interface EngineStoreInstance extends StoreInstanceLike { clearPersisted(): void }
+/** Canonical engine instance derived from the handle's create contract. */
+type EngineStoreInstance = ReturnType<EngineStoreHandle['create']>

 /** Store axis record: one per live handle, dropped when the last holding entry unloads. */
 interface StoreAxisRecord {
--- a/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts
+++ b/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts
@@ -36,7 +36,10 @@ 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 }])
+    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", () => {
--- a/packages/client/runtime/tests/event-script.ts
+++ b/packages/client/runtime/tests/event-script.ts
@@ -92,8 +92,19 @@ export const ev = {
    at(seq, { type: 'command/run', data: { commandId, name, args, source: { kind: 'user' } } }),
  commandRunWithoutInput: (seq: number, commandId: string, name: string): SessionEvent =>
    at(seq, { type: 'command/run', data: { commandId, name, source: { kind: 'user' } } }),
-  commandDone: (seq: number, commandId: string, kind: 'success' | 'error' = 'success', text?: string): SessionEvent =>
-    at(seq, { type: 'command/done', data: { commandId, kind, ...text === undefined ? {} : { text } } }),
+  commandDone: (
+    seq: number,
+    commandId: string,
+    kind: 'success' | 'error' = 'success',
+    text?: string,
+    sourceEventSeq?: number,
+  ): SessionEvent =>
+    at(seq, { type: 'command/done', data: {
+      commandId,
+      kind,
+      ...text === undefined ? {} : { text },
+      ...sourceEventSeq === undefined ? {} : { sourceEventSeq },
+    } }),
  /** A compaction's log-only `compact/summary` provenance record. */
  compactSummary: (seq: number, summary: string, start: number, end: number): SessionEvent =>
    at(seq, { type: 'compact/summary', data: {
--- a/packages/client/runtime/tests/fake-api.ts
+++ b/packages/client/runtime/tests/fake-api.ts
@@ -198,6 +198,7 @@ export class FakeApiClient implements IApiClient {
  onSkillList: (payload: unknown) => Promise<RpcResponse<{ skills: SkillEntry[] }>>
    = () => Promise.resolve(ok({ skills: [] }))

+
  readonly commands: IApiClient['commands'] = {
    list: (payload: unknown) => this.record('command.list', payload, this.onCommandList(payload)),
    execute: (payload: unknown) => this.record('command.execute', payload, this.onCommandExecute(payload)),
--- a/packages/client/runtime/tests/subagent-lineage.spec.ts
+++ b/packages/client/runtime/tests/subagent-lineage.spec.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+import type { SessionId, SessionSummary } from '@deepseek-ai/dsh-client-runtime/client'
+import { indexSubagentDescendants } from '@deepseek-ai/dsh-client-runtime/client'
+
+const sid = (id: string) => id as SessionId
+
+function summary(
+  id: string,
+  parentId?: SessionId,
+  origin?: 'subagent',
+  running = false,
+): SessionSummary {
+  return {
+    id: sid(id), displayTitle: id, running, blank: false, updatedAt: 0,
+    ...(parentId === undefined ? {} : { parentId }),
+    ...(origin === undefined ? {} : { origin }),
+  }
+}
+
+function index(...summaries: SessionSummary[]) {
+  return indexSubagentDescendants(Object.fromEntries(
+    summaries.map(item => [item.id, item]),
+  ))
+}
+
+describe('indexSubagentDescendants', () => {
+  it('counts every nested descendant and its exact running state', () => {
+    const owner = summary('owner')
+    const child = summary('child', owner.id, 'subagent')
+    const grandchild = summary('grandchild', child.id, 'subagent', true)
+
+    const result = index(owner, child, grandchild)
+    expect(result.get(owner.id)).toEqual({ count: 2, runningCount: 1 })
+    expect(result.get(child.id)).toEqual({ count: 1, runningCount: 1 })
+  })
+
+  it('stops at ordinary forks and fails soft on cycles and missing parents', () => {
+    const owner = summary('owner')
+    const child = summary('child', owner.id, 'subagent', true)
+    const fork = summary('fork', child.id)
+    const forkChild = summary('fork-child', fork.id, 'subagent', true)
+    const orphan = summary('orphan', sid('missing'), 'subagent', true)
+    const cycleA = summary('cycle-a', sid('cycle-b'), 'subagent')
+    const cycleB = summary('cycle-b', sid('cycle-a'), 'subagent')
+
+    const result = index(owner, child, fork, forkChild, orphan, cycleA, cycleB)
+    expect(result.get(owner.id)).toEqual({ count: 1, runningCount: 1 })
+    expect(result.get(fork.id)).toEqual({ count: 1, runningCount: 1 })
+    expect(result.get(sid('missing'))).toEqual({ count: 1, runningCount: 1 })
+    expect(result.get(cycleA.id)).toEqual({ count: 2, runningCount: 0 })
+    expect(result.get(cycleB.id)).toEqual({ count: 2, runningCount: 0 })
+  })
+})
--- a/packages/client/runtime/tests/transcript-adapter.spec.ts
+++ b/packages/client/runtime/tests/transcript-adapter.spec.ts
@@ -164,6 +164,28 @@ describe('TranscriptAdapter', () => {
    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/* provenance record) and a future type core
@@ -223,8 +245,14 @@ describe('TranscriptAdapter', () => {
        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' },
-        { kind: 'compaction', seq: 5, time: 1_700_000_000_005, summary: 'second' },
+        {
+          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,
+        },
      ])
    })

@@ -296,7 +324,7 @@ describe('TranscriptAdapter', () => {
        ...(summary === undefined ? [] : [summary]),
        checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }),
      ])
-      expect(adapter.nodes()).toEqual([
+      expect(adapter.nodes()).toMatchObject([
        { kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: null },
      ])
    })
@@ -310,7 +338,10 @@ describe('TranscriptAdapter', () => {
        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: '可用摘要' },
+        {
+          kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: '可用摘要',
+          summaryEventSeq: 1, shadowedItemCount: 2, shadowedTokenCount: 100,
+        },
      ])
    })

@@ -324,7 +355,10 @@ describe('TranscriptAdapter', () => {
          source: { kind: 'plugin', plugin: 'compact' },
        }),
      })])
-      expect(adapter.nodes()).toEqual([{ kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: null }])
+      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 non-summary provenance seq before reaching the real one', () => {
@@ -468,20 +502,22 @@ describe('TranscriptAdapter', () => {
      expect(adapter.nodes().map(n => n.kind)).toEqual(['user', 'command'])
    })

-    it('renders the /compact row alongside the marker its own command produced', () => {
-      // The row that reports the compaction is a command node; dropping command
-      // folding would delete it together with every other slash-command row.
+    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', '已压缩'),
+        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: '已压缩' } })
+      expect(nodes[1]).toMatchObject({
+        name: 'compact',
+        outcome: { kind: 'success', text: '已压缩', sourceEventSeq: 2 },
+      })
+      expect(nodes[2]).toMatchObject({ kind: 'compaction', summaryEventSeq: 2 })
    })
  })

--- a/packages/client/runtime/tsconfig.json
+++ b/packages/client/runtime/tsconfig.json
@@ -23,9 +23,6 @@
    {
      "path": "../schema-form"
    },
-    {
-      "path": "../../api/remotes"
-    },
    {
      "path": "../../host/apiproxy"
    },
--- a/packages/client/schema-form/tsdown.config.ts
+++ b/packages/client/schema-form/tsdown.config.ts
@@ -0,0 +1,6 @@
+import { clientLibrary } from '../tsdown.client.ts'
+
+export default clientLibrary(
+  '@deepseek-ai/dsh-client-schema-form',
+  ['lib/types/index.js', 'lib/types/invariant.js'],
+)
--- a/packages/client/test-runtime/tsdown.config.ts
+++ b/packages/client/test-runtime/tsdown.config.ts
@@ -0,0 +1,6 @@
+import { clientLibrary } from '../tsdown.client.ts'
+
+export default clientLibrary(
+  '@deepseek-ai/dsh-client-test-runtime',
+  ['lib/types/index.js', 'lib/types/invariant.js'],
+)
--- a/packages/client/tsdown.client.ts
+++ b/packages/client/tsdown.client.ts
@@ -9,6 +9,7 @@
 * The virtual loader registers each real stylesheet as a watch dependency.
 */
 import { readFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
 import { basename, dirname, relative, resolve as resolvePath, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import type { UserConfig } from 'tsdown'
@@ -34,6 +35,12 @@ export const INLINE_SAFE = /^@deepseek-ai\/dsh-(host-apiproxy|session|llm|tools|
 /** Generated descriptor/codec contribution with no shared runtime identity. */
 const GENERATED_REMOTE = /^@deepseek-ai\/dsh-[a-z0-9]+(?:-[a-z0-9]+)*\/remote$/

+/**
+ * Workspace mode replaces an empty config array with the root defaults. A
+ * falsey entry instead removes this package before entry resolution.
+ */
+const SKIP_WORKSPACE_BUILD: UserConfig = { entry: '' }
+
 /**
 * Documented TEMPORARY exemption, not a platform module (hence not in
 * platform.ts): the snapshot-store engine (createSnapshotStore/defineStore/
@@ -61,19 +68,85 @@ function browserSourcePath(source: string, sourcemapPath: string): string {

 /**
 * Build the tsdown config for one UI plugin package: the node-half lib build
- * plus the browser client bundle. A package-level tsdown.config.ts REPLACES
- * the root workspace shape, so the lib half must be restated here — dropping
- * it leaves the package without lib/index.js and the host Loader cannot
- * import its node half.
+ * plus the browser client bundle. Client packages emit both halves during the
+ * Client pass by default; packages needed for Host reflection may opt into the
+ * earlier Host pass. A package-level tsdown.config.ts REPLACES the root
+ * workspace shape, so the lib half must be restated here — dropping it leaves
+ * the package without lib/index.js and the host Loader cannot import its node
+ * half.
 * @param id - plugin id (package name), stamped into the __ModuleLoader__.load
 * handoff and onto the injected style tags.
 * @param libEntry - node-half entries, spelled at the call site so the
 * package-invariants gate can see `lib/types/invariant.js` in each package's
 * own tsdown.config.ts (a preset-side glob hides it from the mechanical check).
- * @returns tsdown user configs emitting lib/*.js and lib/client.js.
+ * @param options - phase placement, lib overrides, and companion Node configs.
+ * @returns ENV-selected tsdown config for the current build face.
 */
-export function clientBundle(id: string, libEntry: readonly string[]): [UserConfig, UserConfig] {
-  return [{
+export function clientBundle(
+  id: string,
+  libEntry: readonly string[],
+  options: ClientBundleOptions = {},
+): BuildFaceConfig {
+  const lib = clientLibraryConfig(id, libEntry, options.lib)
+  return ({ env }) => {
+    const face = buildFace(env?.DSH_BUILD_FACE)
+    const client = clientConfig(id, face === undefined
+      ? 'src/client/index.ts'
+      : 'lib/types/client/index.js')
+    const node = [lib, ...(options.companions ?? [])]
+    if (face === 'host') return options.hostPhase === true ? node : [SKIP_WORKSPACE_BUILD]
+    if (face === 'client') return options.hostPhase === true ? [client] : [...node, client]
+    return [...node, client]
+  }
+}
+
+/**
+ * Build a Client-only Node library during the Client pass.
+ * @param id - Package name used in tsdown diagnostics.
+ * @param libEntry - Emitted JavaScript entries consumed from `lib/types`.
+ * @returns ENV-selected tsdown config for the Client build face.
+ */
+export function clientLibrary(id: string, libEntry: readonly string[]): BuildFaceConfig {
+  const lib = clientLibraryConfig(id, libEntry)
+  return clientOnly([lib])
+}
+
+/**
+ * Select arbitrary package-local configs only during the Client pass.
+ * @param configs - Node-side configs emitted after Client tsc.
+ * @returns ENV-selected tsdown config for the Client build face.
+ */
+export function clientOnly(configs: readonly UserConfig[]): BuildFaceConfig {
+  return ({ env }) => buildFace(env?.DSH_BUILD_FACE) === 'host'
+    ? [SKIP_WORKSPACE_BUILD]
+    : [...configs]
+}
+
+interface ClientBundleOptions {
+  /** Emit the Node-side artifacts during the Host pass instead of the Client pass. */
+  readonly hostPhase?: boolean
+  /** Additional Node-side configs emitted alongside the package library. */
+  readonly companions?: readonly UserConfig[]
+  /** Overrides for the package's primary Node-side library config. */
+  readonly lib?: UserConfig
+}
+
+type BuildFace = 'host' | 'client' | undefined
+
+type BuildFaceConfig = (inlineConfig: Pick<UserConfig, 'env'>) => UserConfig[]
+
+function buildFace(value: unknown): BuildFace {
+  if (value === undefined || value === 'host' || value === 'client') return value
+  throw new Error(`tsdown: --env.DSH_BUILD_FACE must be host or client, received ${String(value)}`)
+}
+
+function clientLibraryConfig(
+  id: string,
+  libEntry: readonly string[],
+  overrides: UserConfig = {},
+): UserConfig {
+  return {
+    name: id,
    entry: [...libEntry],
    outDir: 'lib',
    format: ['esm'],
@@ -82,8 +155,14 @@ export function clientBundle(id: string, libEntry: readonly string[]): [UserConf
    fixedExtension: false,
    dts: false,
    clean: false,
-  }, {
-    entry: { client: 'src/client/index.ts' },
+    ...overrides,
+  }
+}
+
+function clientConfig(id: string, entry: string): UserConfig {
+  return {
+    name: `${id}/client`,
+    entry: { client: entry },
    // Browser bundle lands next to the node half (single lib/ artifact dir;
    // the entryFileNames pin keeps it exactly lib/client.js). clean must stay
    // off — a default clean would wipe the node-half output emitted above.
@@ -139,7 +218,7 @@ export function clientBundle(id: string, libEntry: readonly string[]): [UserConf
      name: 'dsh-css-modules-inline',
      resolveId(source: string, importer: string | undefined) {
        if (!source.endsWith('.module.css')) return null
-        const abs = importer !== undefined ? resolvePath(dirname(importer), source) : source
+        const abs = importer !== undefined ? sourceAssetPath(source, importer) : source
        return CSS_VIRTUAL_PREFIX + abs + CSS_VIRTUAL_SUFFIX
      },
      async load(virtualId: string) {
@@ -151,7 +230,7 @@ export function clientBundle(id: string, libEntry: readonly string[]): [UserConf
        const { code, exports: cssExports } = transform({
          filename: fileId,
          code: source,
-          cssModules: { pattern: `[hash]_[local]` },
+          cssModules: { pattern: '[hash]_[local]' },
          minify: true,
        })
        const classMap: Record<string, string> = {}
@@ -160,13 +239,13 @@ export function clientBundle(id: string, libEntry: readonly string[]): [UserConf
        return [
          `const css = ${JSON.stringify(code.toString())};`,
          `const tagId = ${JSON.stringify(`${id}/${basename(fileId)}`)};`,
-          `if (typeof document !== 'undefined' && document.querySelector('style[data-plugin-css=' + JSON.stringify(tagId) + ']') === null) {`,
-          `  const tag = document.createElement('style');`,
+          'if (typeof document !== \'undefined\' && document.querySelector(\'style[data-plugin-css=\' + JSON.stringify(tagId) + \']\') === null) {',
+          '  const tag = document.createElement(\'style\');',
          `  tag.dataset.plugin = ${JSON.stringify(id)};`,
-          `  tag.dataset.pluginCss = tagId;`,
-          `  tag.textContent = css;`,
-          `  document.head.appendChild(tag);`,
-          `}`,
+          '  tag.dataset.pluginCss = tagId;',
+          '  tag.textContent = css;',
+          '  document.head.appendChild(tag);',
+          '}',
          `export default ${JSON.stringify(classMap)};`,
        ].join('\n')
      },
@@ -179,8 +258,18 @@ export function clientBundle(id: string, libEntry: readonly string[]): [UserConf
      // without exposing that tree as an HTTP route.
      sourcemapPathTransform: browserSourcePath,
      banner: `window.__ModuleLoader__.load({ id: ${JSON.stringify(id)}, factory: (require) => {`,
-      footer: `return module.exports; } });`,
+      footer: 'return module.exports; } });',
      intro: 'var module = { exports: {} }; var exports = module.exports;',
    },
-  }]
+  }
+}
+
+/** Resolve an emitted JS asset import against its source-tree counterpart. */
+function sourceAssetPath(source: string, importer: string): string {
+  const emitted = resolvePath(dirname(importer), source)
+  if (existsSync(emitted)) return emitted
+  const marker = `${sep}lib${sep}types${sep}`
+  const boundary = emitted.indexOf(marker)
+  if (boundary < 0) return emitted
+  return resolvePath(emitted.slice(0, boundary), 'src', emitted.slice(boundary + marker.length))
 }
--- 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: bf4cc11fa8e5d512f6cd802321dd835135af03f4
-README.zh.md: 2dc09eb4a9408dde615bd2fc982e01291de3840b
+README.md: 4e6ecfdb2d3085b196f08f440a09cdfc9f4863bb
+README.zh.md: 8dc474aad64dafbabd0db0a300a63e72588e75f2
--- 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, an animated left-to-right gradient `Deep diving...` turn status, per-tool row slot with a bash sample registrant and the todo row), composer dock (session stats sticky with the input), input dock (hairline-separated queue rows plus the todo plan strip), minimal details panel, scope-addressed ConversationService. Contract: api-contracts v3 §7 plus the slot terminal design (store seat / props shares).

-Compaction renders as one collapsed row at the checkpoint's flow position without replacing the transcript above it. The disclosure renders the checkpoint's `compact/summary` provenance; when that event is outside the loaded window, the row remains visible but non-expandable. The framed checkpoint payload is model-facing and never renders.
+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.

 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.

@@ -64,7 +64,6 @@ None; this package neither assembles nor sends a provider request.

 ## Known Limitations and Deferred Work

- **Compaction markers show no scale** — the row does not yet report how many messages or which range the checkpoint replaced.
 - **Stats-line durations and speeds cover the in-window flow only** — LLM and tool wall times plus the TTFT and throughput averages fold the snapshot's assistant `timing` and tool call/result pairs, so nodes outside the loaded event window (older history) are not counted.
 - **The details panel has no entry point** — `ChatViewInjected.openDetails` is implemented but uncalled, so the raw selected-call display is unreachable in the assembled application. There is no Input/Output/Metadata switch, Prev/Next stepping, or trajectory deep link.
 - **Assistant per-message paging is a reserved slot** — drawn in the design, not implemented. The finalized content IconActions row (copy / clock / branch) ships under the last content-text assistant of each turn that has ended; mid-turn narration, Think-only nodes, and every node of a turn still producing steps stay chrome-free. Branch stays disabled unless that message is also the last transcript node of a completed turn; when enabled, it forks through that turn, increments the inherited title on the client, and opens the child. A fork or rename failure leaves the source selected ([decision](../../../.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.md)).
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -4,7 +4,7 @@

 会话领域：骨架（标题栏／标签页／编辑器／空状态）、聊天视图（分组步骤摘要流、流式尾部隔离、带从左到右动态渐变的 `Deep diving...` 轮次状态、逐工具行 slot 及一个 bash 示例注册方与 todo 行）、编辑器 dock（与输入区一同 sticky 的会话统计行）、输入区 dock（带发丝分界线的队列行加 todo 计划条）、最小详情面板、按 scope 寻址的 ConversationService。契约：api-contracts v3 §7 加 slot 终端设计（store seat／props share）。

-压缩（compaction）在检查点自身的消息流位置渲染为一行折叠标记，不替换其上方的 transcript（文本记录）。展开内容来自检查点溯源的 `compact/summary`；该事件位于已加载窗口之外时，标记仍然可见但不可展开。面向模型的带框检查点载荷绝不渲染。
+压缩（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 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。

@@ -64,7 +64,6 @@ Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。Qu

 ## 已知限制与暂缓事项

- **压缩标记不显示规模**：该行尚不报告检查点替换了多少条消息或哪段范围。
 - **统计行的耗时与速率只覆盖窗口内消息流**：LLM 与工具墙钟时间以及 TTFT 与吞吐平均值由快照的 assistant `timing` 与工具 call/result 配对折算，落在已加载事件窗口之外的节点（更早的历史）不计入。
 - **详情面板没有入口**：`ChatViewInjected.openDetails` 虽已实现却无人调用，因此以原始形式显示已选择调用的那部分在组装后的应用中不可达。没有 Input/Output/Metadata 切换、Prev/Next 步进，也没有 trajectory 深链接。
 - **assistant 逐消息分页是预留 slot**：设计中已有图稿，尚未实现。已定稿的内容 IconActions 行（复制／时钟／分支）只挂在每个已结束轮次中最后一条带 text 内容的 assistant 下；轮次中间的叙述、纯 Think 节点，以及仍在产出步骤的轮次里的所有节点都不带 chrome。除非该消息同时也是已完成轮次的最后一个 transcript 节点，否则分支保持禁用；启用后，它会 fork 到该轮次末尾，在 client 端递增继承标题并打开子会话。fork 或改名失败时源会话保持选中（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.md)）。
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -32,6 +32,7 @@ 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 { GenericToolCard } from './GenericToolCard.tsx'
 import { MessageItem, PendingSteeringBubble } from './MessageItem.tsx'
@@ -267,17 +268,21 @@ const ToolGroup = memo(function ToolGroup({ renderSlot, results, openFile, selec
 /** 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, t }: {
+const CommandRow = memo(function CommandRow({ renderSlot, node, compaction, t }: {
  renderSlot: RenderToolRow
  node: CommandNode
+  compaction?: Extract<ConversationNode, { kind: 'compaction' }>
  t: ChatViewSlotProps['t']
 }) {
-  const owner = useMemo(() => ({ node }), [node])
+  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: <GenericCommandCard {...owner} t={t} />,
+        fallback,
      })}
    </div>
  )
@@ -580,6 +585,16 @@ export function ChatView({
        />
      )
    }
+    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
@@ -642,9 +657,17 @@ export function ChatView({
            <div
              key={item.key}
              className={css.flowItem}
-              data-chat-anchor-key={item.kind === 'node' ? `node:${String(item.node.seq)}` : undefined}
+              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 : 'tool-group'}
+              data-chat-flow-kind={item.kind === 'node'
+                ? item.node.kind
+                : item.kind === 'command-compaction'
+                  ? item.kind
+                  : 'tool-group'}
            >
              {renderItem(item)}
            </div>
--- a/packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx
@@ -0,0 +1,40 @@
+// CompactionCommandCard: the `/compact` command's running row and its
+// successful checkpoint disclosure. Outcomes without a checkpoint keep the
+// generic command card so no-history, cancellation, and failures retain their
+// complete handler-authored text.
+
+import { IconApiOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ChatViewSlotProps, CommandRowOwnerProps } from '../contract/slots.ts'
+import { CompactionItem } from './CompactionItem.tsx'
+import { GenericCommandCard } from './GenericCommandCard.tsx'
+import { ToolRow } from './ToolRow.tsx'
+
+interface CompactionCommandCardProps extends CommandRowOwnerProps {
+  t: ChatViewSlotProps['t']
+}
+
+/** Render one manual compaction lifecycle without duplicating its checkpoint marker. */
+export function CompactionCommandCard({ node, compaction, t }: CompactionCommandCardProps) {
+  if (compaction !== undefined) {
+    return (
+      <CompactionItem
+        node={compaction}
+        title="compact"
+        fallbackSummary={node.outcome?.text ?? null}
+        t={t}
+      />
+    )
+  }
+  if (node.outcome !== null) return <GenericCommandCard node={node} t={t} />
+  return (
+    <ToolRow
+      t={t}
+      variant="others"
+      icon={<IconApiOutline14 size={14} />}
+      title="compact"
+      summary={t('message.compaction.running')}
+      body={null}
+      state="running"
+    />
+  )
+}
--- a/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx
+++ b/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx
@@ -9,6 +9,7 @@
 import { memo, useState } from 'react'
 import type { CompactionSummaryNode } from '@deepseek-ai/dsh-client-runtime/client'
 import {
+  IconApiOutline14,
  IconChevronDownOutline14,
  IconChevronRightOutline14,
  MarkdownText,
@@ -18,6 +19,10 @@ import css from './MessageItem.module.css'

 interface CompactionItemProps {
  node: CompactionSummaryNode
+  /** Optional command title for a manual compaction folded into this marker. */
+  title?: string
+  /** Command settlement text used when structured compaction counts are unavailable. */
+  fallbackSummary?: string | null
  /** The owning view's locale seat. */
  t: ChatViewSlotProps['t']
 }
@@ -27,10 +32,22 @@ interface CompactionItemProps {
 * @param props - the marker node off the snapshot cache.
 * @returns the marker row, with the summary disclosure when one is available.
 */
-export const CompactionItem = memo(function CompactionItem({ node, t }: CompactionItemProps) {
+export const CompactionItem = memo(function CompactionItem({
+  node,
+  title,
+  fallbackSummary,
+  t,
+}: CompactionItemProps) {
  const [expanded, setExpanded] = useState(false)
  const expandable = node.summary !== null
  const open = expandable && expanded
+  const summary = node.shadowedItemCount !== null && node.shadowedTokenCount !== null
+    ? t('message.compaction.completed', {
+      items: node.shadowedItemCount,
+      tokens: node.shadowedTokenCount,
+    })
+    : fallbackSummary
+      ?? (expandable ? t('message.compaction.expand') : t('message.compaction.unavailable'))
  return (
    <div className={css.compactionRow}>
      <button
@@ -40,14 +57,20 @@ export const CompactionItem = memo(function CompactionItem({ node, t }: Compacti
        aria-expanded={expandable ? open : undefined}
        onClick={() => { setExpanded(value => !value) }}
      >
-        <span className={css.compactionLeading}>
-          {open ? <IconChevronDownOutline14 /> : <IconChevronRightOutline14 />}
+        <span className={css.compactionLeading} aria-hidden>
+          <span className={css.compactionContextIcon} data-compaction-icon="context">
+            <IconApiOutline14 />
+          </span>
+          <span
+            className={css.compactionDisclosureIcon}
+            data-compaction-disclosure={open ? 'expanded' : 'collapsed'}
+          >
+            {open ? <IconChevronDownOutline14 /> : <IconChevronRightOutline14 />}
+          </span>
        </span>
-        <span className={css.compactionTitle}>{t('message.compaction')}</span>
+        <span className={css.compactionTitle}>{title ?? t('message.compaction')}</span>
        <span className={css.compactionSep} aria-hidden />
-        <span className={css.compactionSummary}>
-          {expandable ? t('message.compaction.expand') : t('message.compaction.unavailable')}
-        </span>
+        <span className={css.compactionSummary}>{summary}</span>
      </button>
      {open && node.summary !== null
        && <div className={css.compactionBody}><MarkdownText text={node.summary} /></div>}
--- a/packages/client/ui-conversation/src/client/chat/MessageItem.module.css
+++ b/packages/client/ui-conversation/src/client/chat/MessageItem.module.css
@@ -33,9 +33,9 @@
  padding: 2px 0;
 }

-/* Compaction marker: one dim 24px row with a chevron disclosure for the
-   summary body. Dimmed title (not label-primary) — the row is a boundary
-   notice, not conversation content. */
+/* Compaction marker: one dim 24px row with a context icon at rest and a
+   hover/focus disclosure for the summary body. Dimmed title (not
+   label-primary) — the row is a boundary notice, not conversation content. */
 .compactionRow {
  padding: 2px 0;
 }
@@ -65,15 +65,36 @@

 .compactionLeading {
  flex: none;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
+  display: inline-grid;
+  place-items: center;
  width: 16px;
  height: 16px;
  margin-right: 6px;
  color: var(--dsw-alias-label-secondary);
 }

+.compactionContextIcon,
+.compactionDisclosureIcon {
+  display: inline-flex;
+  grid-area: 1 / 1;
+  align-items: center;
+  justify-content: center;
+}
+
+.compactionDisclosureIcon {
+  opacity: 0;
+}
+
+.compactionButton:not(:disabled):hover .compactionContextIcon,
+.compactionButton:not(:disabled):focus-visible .compactionContextIcon {
+  opacity: 0;
+}
+
+.compactionButton:not(:disabled):hover .compactionDisclosureIcon,
+.compactionButton:not(:disabled):focus-visible .compactionDisclosureIcon {
+  opacity: 1;
+}
+
 .compactionTitle {
  flex: none;
  font-size: 14px;
--- a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
+++ b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
@@ -137,29 +137,27 @@ 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. Two
- * shapes decorate: legacy `<skill>name</skill>` spans (pre-decision-21
- * history) and plain-text `/name` / `@name` word-boundary tokens (decision
- * 21: 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).
+ * 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
+ * scan as the composer, minus the lexicon: sent tokens were validated at
+ * compose time, so shape alone decorates).
 */
 function projectUserText(text: string): ReactNode {
-  const re = /<skill>([^<]+)<\/skill>|(^|\s)([/@][\w-]+)(?=\s|$)/g
+  const re = /(^|\s)([/@][\w-]+)(?=\s|$)/g
  const parts: ReactNode[] = []
  let cursor = 0
  let m: RegExpExecArray | null
  while ((m = re.exec(text)) !== null) {
-    const legacy = m[1] !== undefined
-    const tokenStart = legacy ? m.index : m.index + (m[2]?.length ?? 0)
-    const label = legacy ? `/${m[1]}` : m[3] ?? ''
+    const tokenStart = m.index + (m[1]?.length ?? 0)
+    const label = m[2] ?? ''
    if (tokenStart > cursor) parts.push(<MessageText key={cursor} text={text.slice(cursor, tokenStart)} />)
    parts.push(
      <span key={tokenStart} className={css.refChip} data-ref-chip={label.startsWith('@') ? 'subagent' : 'skill'}>
        {label}
      </span>,
    )
-    cursor = legacy ? m.index + m[0].length : tokenStart + label.length
+    cursor = tokenStart + label.length
  }
  if (parts.length === 0) return <MessageText text={text} />
  if (cursor < text.length) parts.push(<MessageText key={cursor} text={text.slice(cursor)} />)
--- a/packages/client/ui-conversation/src/client/chat/chat-flow.ts
+++ b/packages/client/ui-conversation/src/client/chat/chat-flow.ts
@@ -9,13 +9,48 @@
 * flow share their gates.
 */
 import type {
-  AssistantBlock, ConversationNode, ConversationSnapshot, ToolResultNode,
+  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.
@@ -115,9 +150,28 @@ export function assistantBranchSeqs(
 */
 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]
@@ -138,7 +192,13 @@ export function deriveChatFlow(nodes: readonly ConversationNode[]): ChatFlowItem
      }
    } else {
      group = null
-      items.push({ kind: 'node', key: `n${node.seq}`, node })
+      items.push({
+        kind: 'node',
+        key: node.kind === 'command' && node.name === 'compact'
+          ? `c${node.commandId}`
+          : `n${node.seq}`,
+        node,
+      })
    }
  }
  return items
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -3,7 +3,7 @@ import type { ReactNode, RefObject } from 'react'
 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 { CommandNode, CompactionSummaryNode, ConversationNode, ConversationSnapshot, ObservableSnapshot, PendingInteraction, PendingWait, SessionId, ToolCallBlock, WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
 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'
@@ -217,14 +217,16 @@ export type ToolRowProps = PropsRuntime<'conversation.chat.toolview'>
 /**
 * Owner share of the per-command row slot: the frozen {@link CommandNode}
 * slice off the snapshot (cache-stable reference — memo premise). The node
- * carries the whole lifecycle (structured name/args, pairing id,
- * outcome-or-executing), so a
- * registrant needs no second data channel; domain state arrives through its
- * own projection cell.
+ * carries the whole lifecycle (structured name/args, pairing id, and
+ * outcome-or-executing). A successful domain command may also carry the
+ * explicitly linked projection node needed to fold two log records into one
+ * presentation row.
 */
 export interface CommandRowOwnerProps {
  /** Folded command lifecycle node (run + optional done). */
  node: CommandNode
+  /** Explicitly linked compaction checkpoint for the settled `/compact` presentation. */
+  compaction?: CompactionSummaryNode
 }

 /** Full props of a registered command-row component (same shape rule as {@link ToolRowProps}). */
--- a/packages/client/ui-conversation/src/client/locales.ts
+++ b/packages/client/ui-conversation/src/client/locales.ts
@@ -80,6 +80,8 @@ export const zh = {
  'message.context.recall.truncated': '已截断',
  'message.steering': '插话',
  'message.compaction': '上下文已压缩',
+  'message.compaction.running': '正在压缩…',
+  'message.compaction.completed': '已压缩 {items} 条历史记录（约 {tokens} tokens）',
  'message.compaction.expand': '点击查看压缩摘要',
  'message.compaction.unavailable': '压缩摘要不可用',
  'message.unknownSurface': '未知 surface 事件：{type}',
@@ -220,6 +222,8 @@ export const en = {
  'message.context.recall.truncated': 'truncated',
  'message.steering': 'Interjection',
  'message.compaction': 'Context compacted',
+  'message.compaction.running': 'Compacting context…',
+  'message.compaction.completed': 'Compacted {items} history items (~{tokens} tokens)',
  'message.compaction.expand': 'View compaction summary',
  'message.compaction.unavailable': 'Compaction summary unavailable',
  'message.unknownSurface': 'Unknown surface event: {type}',
--- a/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
@@ -691,11 +691,15 @@ describe('MessageItem arms', () => {
      <MessageItem t={t} node={{
        kind: 'compaction', seq: 5, time: 1_000,
        summary: '## 摘要标题\n\n保留的事实。',
+        summaryEventSeq: 4,
+        shadowedItemCount: 16,
+        shadowedTokenCount: 11_309,
      }}
      />,
    )
    const row = view.getByRole('button', { name: /上下文已压缩/ })
    expect(row.getAttribute('aria-expanded')).toBe('false')
+    expect(view.getByText('已压缩 16 条历史记录（约 11309 tokens）')).toBeTruthy()
    expect(view.queryByText(/保留的事实/)).toBeNull()
    fireEvent.click(row)
    expect(row.getAttribute('aria-expanded')).toBe('true')
@@ -705,7 +709,10 @@ describe('MessageItem arms', () => {
  })

  it('a marker whose provenance fell outside the window is not expandable', () => {
-    const view = render(<MessageItem t={t} node={{ kind: 'compaction', seq: 6, time: 1_000, summary: null }} />)
+    const view = render(<MessageItem t={t} node={{
+      kind: 'compaction', seq: 6, time: 1_000, summary: null,
+      summaryEventSeq: null, shadowedItemCount: null, shadowedTokenCount: null,
+    }} />)
    const row = view.getByRole('button', { name: /上下文已压缩/ })
    expect(row).toHaveProperty('disabled', true)
    expect(row.getAttribute('aria-expanded')).toBeNull()
@@ -864,6 +871,7 @@ describe('MessageItem arms', () => {
    view.rerender(<MessageItem t={t} node={node} retryActive />)
    expect(view.getByRole('status').textContent).toBe('正在重试模型请求（1/2） · 1s')
  })
+
 })

 describe('formatMessageClock', () => {
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -7,7 +7,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { Profiler } from 'react'
 import { act, cleanup, fireEvent, render, within } from '@testing-library/react'
 import type {
-  AssistantMessageNode, CommandNode, ConversationNode, ConversationSnapshot,
+  AssistantMessageNode, CommandNode, CompactionSummaryNode, ConversationNode, ConversationSnapshot,
  ModelRetryNode, RunningToolCall, SessionId, SessionListState, ToolResultNode, TurnErrorNode,
  UserMessageNode, WorkspaceListState,
 } from '@deepseek-ai/dsh-client-runtime/client'
@@ -93,6 +93,19 @@ const toolResult = (seq: number, callId: string, name = 'bash'): ToolResultNode
 const runningCall = (callId: string, name = 'bash'): RunningToolCall => ({
  callId, name, argsRaw: `{"command":"cmd-${callId}"}`, turn: 2, step: 1, time: 1_000, callView: null,
 })
+const command = (over: Partial<CommandNode> = {}): CommandNode => ({
+  kind: 'command', seq: 5, time: 5_000, commandId: 'cmd-1' as CommandNode['commandId'],
+  name: 'plan', args: '', outcome: { kind: 'success', text: '已进入 plan mode' },
+  ...over,
+})
+const compaction = (over: Partial<CompactionSummaryNode> = {}): CompactionSummaryNode => ({
+  kind: 'compaction', seq: 8, time: 8_000,
+  summary: '## 压缩摘要\n\n保留的事实。',
+  summaryEventSeq: 7,
+  shadowedItemCount: 16,
+  shadowedTokenCount: 11_309,
+  ...over,
+})

 /** Empty sessions-list hook for the global standard-kit seat. */
 function emptySessions() {
@@ -212,6 +225,79 @@ describe('chat-flow derivation', () => {
    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.
@@ -1172,11 +1258,6 @@ describe('ChatView', () => {
  })

  it('renders command nodes as durable rows: settled text, error state, executing spinner, run-less soft-fall', () => {
-    const command = (over: Partial<CommandNode>): CommandNode => ({
-      kind: 'command', seq: 5, time: 5_000, commandId: 'cmd-1' as CommandNode['commandId'],
-      name: 'plan', args: '', outcome: { kind: 'success', text: '已进入 plan mode' },
-      ...over,
-    })
    // Settled success: the bare command name is the title, the outcome text
    // the summary — neither the dispatched `/` nor its arguments reach the row
    // (the settlement text already says what the command did).
@@ -1211,4 +1292,65 @@ describe('ChatView', () => {
    expect(ov.getByText('命令')).toBeTruthy()
    expect(ov.getByText('已完成')).toBeTruthy()
  })
+
+  it('renders /compact as one stateful disclosure from running through completion', () => {
+    const running = command({
+      commandId: 'cmd-compact' as CommandNode['commandId'],
+      name: 'compact',
+      outcome: null,
+    })
+    const h = makeHarness({ nodes: [running] })
+    const view = render(<h.ChatView {...h.props} />)
+    expect(view.getByText('正在压缩…')).toBeTruthy()
+    expect(view.container.querySelector('[data-state="running"]')).not.toBeNull()
+
+    act(() => {
+      h.set({
+        nodes: [{
+          ...running,
+          outcome: {
+            kind: 'success',
+            text: 'Compacted 16 history items (~11309 tokens).',
+            sourceEventSeq: 7,
+          },
+        }, compaction()],
+      })
+    })
+
+    expect(view.queryByText('正在压缩…')).toBeNull()
+    expect(view.queryByText('上下文已压缩')).toBeNull()
+    expect(view.getByText('已压缩 16 条历史记录（约 11309 tokens）')).toBeTruthy()
+    const row = view.getByRole('button', { name: /compact/ })
+    expect(row.getAttribute('aria-expanded')).toBe('false')
+    expect(row.querySelector('[data-compaction-icon="context"]')).not.toBeNull()
+    expect(row.querySelector('[data-compaction-disclosure="collapsed"]')).not.toBeNull()
+    expect(view.queryByText('保留的事实。')).toBeNull()
+    fireEvent.click(row)
+    expect(row.getAttribute('aria-expanded')).toBe('true')
+    expect(row.querySelector('[data-compaction-disclosure="expanded"]')).not.toBeNull()
+    expect(view.getByRole('heading', { name: '压缩摘要' })).toBeTruthy()
+  })
+
+  it('keeps /compact no-history and error settlements on the generic command row', () => {
+    const noHistory = makeHarness({
+      nodes: [command({
+        name: 'compact',
+        outcome: { kind: 'success', text: 'No compactable history yet.' },
+      })],
+    })
+    const noHistoryView = render(<noHistory.ChatView {...noHistory.props} />)
+    expect(noHistoryView.getByText('No compactable history yet.')).toBeTruthy()
+    expect(noHistoryView.queryByRole('button')).toBeNull()
+
+    const failed = makeHarness({
+      nodes: [command({
+        commandId: 'cmd-compact-failed' as CommandNode['commandId'],
+        name: 'compact',
+        outcome: { kind: 'error', text: 'Compaction cancelled.' },
+      })],
+    })
+    const failedView = render(<failed.ChatView {...failed.props} />)
+    expect(failedView.getByText('Compaction cancelled.')).toBeTruthy()
+    expect(failedView.container.querySelector('[data-state="error"]')).not.toBeNull()
+  })
 })
--- a/packages/client/ui-deliverables/tests/produced-files.spec.tsx
+++ b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
@@ -73,6 +73,7 @@ describe('producedForClosing derivation', () => {
    expect(producedForClosing(nodes, 999)).toEqual([])
  })

+
  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'),
--- a/packages/client/ui-goal/tsconfig.json
+++ b/packages/client/ui-goal/tsconfig.json
@@ -15,7 +15,7 @@
      "path": "../locale"
    },
    {
-      "path": "../../api/remotes"
+      "path": "../../api/remotes/tsconfig.client.json"
    },
    {
      "path": "../runtime"
--- 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: cf4e50630339c4055e9ae2df37246b814af06966
-README.zh.md: 2b9158fa4419bf07f496fce47c938744f2a4233f
+README.md: 66f23d3f77adae23fcebd3adbb6c5c47ce16ae2f
+README.zh.md: dcb35c624aca73b558532210750f684e5cc54e85
--- a/packages/client/ui-models/README.md
+++ b/packages/client/ui-models/README.md
@@ -4,11 +4,11 @@ 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 literal key or 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 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.

-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 literal `apiKey` secret sidecar or 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.
+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.

-Every edit lands as `settings.mutate` path ops against the stored section — a set per changed field, an unset per cleared one, and a single unset for a deleted provider row. The page only ever holds the REDACTED descriptor, so it names the fields it can see rather than rebuilding a section: a stored literal secret it never received is mentioned by no op and survives. DeepSeek's `models` is one replace-by-value array: the editor shows inherited effective rows until the first model edit materializes the complete array in the user layer, while reset unsets that override. A row carries the model id and display name; its context window and output cap sit behind the row's own disclosure, the same shape the pi-ai provider form uses. Either capacity is typed as a count with an optional decimal `K` or `M` suffix (`256K`, `1M`; `1M` is 1000K) and stored as the plain count, spelled back in the shortest form that round-trips. Empty ids, duplicate ids, empty explicit names, and unreadable, non-positive, or fractional capacities fail before any write. A typed API key is judged on its own field the same way: after trimming, it must be non-empty and every character must be printable ASCII (`[\x21-\x7E]`), which is exactly what an HTTP header value can carry — the twin of `normalizeApiKey` in `@deepseek-ai/dsh-llm`, mirrored here because the source-plane split forbids importing it. A value shaped like a pasted `NAME=value` environment line or wrapped in matching quotes is refused as the same format failure; that paste-shape heuristic runs only in the browser, since a false positive in a resolver would leave the environment refusing the key as well. A field holding only whitespace fails rather than being silently dropped, while an empty field is not a failure at all: it means keep the stored key on an editor card, and authenticate some other way on a create card. A refused key blocks both the write and the endpoint interrogation, so the page never spends a round trip to be told what the field already says. Each settings write carries the card's current `revision`, so a concurrent write from another tab or an external `settings.yaml` edit is refused as `settings-conflict`; after settings commit, the card adopts the returned redacted user subtree and revision before storing the credential, which makes a failed credential stage retry only that stage. Deletion removes a configured, writable credential only when the profile names the page's derived `<ROUTE>_API_KEY` target, then unsets the profile; both operations are idempotent, and a partial failure remains in the identified confirmation dialog for retry. Environment credentials, custom references, and credentials whose target cannot be identified remain untouched. The page refetches on the pushed invalidations (`settings/changed`, `credentials/changed`, `models/changed`, and `connection/reset`) once it has loaded, so an external `settings.yaml` edit, a second tab, or a settings-born route converges without polling.
+Every edit lands as `settings.mutate` path ops against the stored section — a set per changed field, an unset per cleared one, and a single unset for a deleted provider row. The page only ever holds the REDACTED descriptor, so it mutates the fields it can see rather than rebuilding a section. DeepSeek's `models` is one replace-by-value array: the editor shows inherited effective rows until the first model edit materializes the complete array in the user layer, while reset unsets that override. A row carries the model id and display name; its context window and output cap sit behind the row's own disclosure, the same shape the pi-ai provider form uses. Either capacity is typed as a count with an optional decimal `K` or `M` suffix (`256K`, `1M`; `1M` is 1000K) and stored as the plain count, spelled back in the shortest form that round-trips. Empty ids, duplicate ids, empty explicit names, and unreadable, non-positive, or fractional capacities fail before any write. A typed API key is judged on its own field the same way: after trimming, it must be non-empty and every character must be printable ASCII (`[\x21-\x7E]`), which is exactly what an HTTP header value can carry — the twin of `normalizeApiKey` in `@deepseek-ai/dsh-llm`, mirrored here because the source-plane split forbids importing it. A value shaped like a pasted `NAME=value` environment line or wrapped in matching quotes is refused as the same format failure; that paste-shape heuristic runs only in the browser, since a false positive in a resolver would leave the environment refusing the key as well. A field holding only whitespace fails rather than being silently dropped, while an empty field is not a failure at all: it means keep the stored key on an editor card, and authenticate some other way on a create card. A refused key blocks both the write and the endpoint interrogation, so the page never spends a round trip to be told what the field already says. Each settings write carries the card's current `revision`, so a concurrent write from another tab or an external `settings.yaml` edit is refused as `settings-conflict`; after settings commit, the card adopts the returned redacted user subtree and revision before storing the credential, which makes a failed credential stage retry only that stage. Deletion removes a configured, writable credential only when the profile names the page's derived `<ROUTE>_API_KEY` target, then unsets the profile; both operations are idempotent, and a partial failure remains in the identified confirmation dialog for retry. Environment credentials, custom references, and credentials whose target cannot be identified remain untouched. The page refetches on the pushed invalidations (`settings/changed`, `credentials/changed`, `models/changed`, and `connection/reset`) once it has loaded, so an external `settings.yaml` edit, a second tab, or a settings-born route converges without polling.

 ## Model list and endpoint interrogation

--- a/packages/client/ui-models/README.zh.md
+++ b/packages/client/ui-models/README.zh.md
@@ -4,11 +4,11 @@

 模型设置插件：提供方配置页和按条件显示的 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 但未声明的存活路由不属于可修复配置。若 `apiKey` 字面量对应的 secret 槽位标记为已设置，或凭据引用已配置，该步骤会直接完成而不渲染，其中包括来自启动环境且只读的凭据。只有已挂载且活跃、引用可写但尚未配置的适配器才会显示前往「设置」Models 分区的页面；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，该步骤绝不持有 secret。适配器缺失、路由不活跃、联接失败、部署只读或设置／凭据能力不可用时，该步骤均不渲染并直接完成，以免首次使用引导阻塞产品；Models 页仍是诊断界面。
+前序首次使用引导页面完成后，DeepSeek 步骤会从同一个联接快照得出 `deepseek-official` 的就绪状态。它通过 `llm-deepseek` 的可配置提供方声明识别官方适配器，因此同 id 但未声明的存活路由不属于可修复配置。凭据引用已配置时，该步骤会直接完成而不渲染，其中包括来自启动环境且只读的凭据。只有已挂载且活跃、引用可写但尚未配置的适配器才会显示前往「设置」Models 分区的页面；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，该步骤绝不持有 secret。适配器缺失、路由不活跃、联接失败、部署只读或设置／凭据能力不可用时，该步骤均不渲染并直接完成，以免首次使用引导阻塞产品；Models 页仍是诊断界面。

-每一次编辑都以 `settings.mutate` 的路径 op 落到已存分节上——每个变更字段一条 set、每个清空字段一条 unset、删除提供方行则是单独一条 unset。页面自始至终只持有**脱敏后**的 descriptor，因此它点名自己看得见的字段，而不是重建分节：一个它从未收到过的已存字面机密不会被任何 op 提及，也就得以留存。DeepSeek 的 `models` 是一个按值整体替换的数组：编辑器会显示继承而来的生效模型行，直到第一次模型编辑将完整数组具化到用户层；重置则会取消该覆盖。每个模型行承载模型 ID 与显示名称，其上下文窗口与最大输出 token 数则收在该行自己的折叠区里，与 pi-ai 提供方表单采用的形态相同。两项容量都按数值键入，可带十进制的 `K` 或 `M` 后缀（`256K`、`1M`；`1M` 即 1000K），存储为纯数值，回显时写成能够往返的最短形式。空 ID、重复 ID、显式填写的空名称，以及无法读取、非正数或非整数的容量都会在写入前失败。键入的 API 密钥同样在它自己的字段上被判定：trim 之后必须非空，且每个字符都是可打印 ASCII（`[\x21-\x7E]`）——这正是 HTTP 标头值所能承载的范围，是 `@deepseek-ai/dsh-llm` 中 `normalizeApiKey` 的孪生体，因源码平面分割禁止直接引入而在此镜像。形如整行粘贴的 `NAME=value` 环境变量或首尾成对引号包裹的值，会以同一条格式失败被拒绝；该粘贴形状启发式只在浏览器中运行，因为 resolver 中的一次误判会连带让环境变量这条路也拒绝该密钥。只含空白的输入框会失败而不是被静默丢弃；留空则完全不是失败：在编辑卡片上意味着保持已存储的密钥，在新建卡片上则意味着以其他方式鉴权。被拒绝的密钥会同时拦截写入与端点探测，因此页面不会白花一次往返去换取字段上已经写明的答案。每次 settings 写入都携带卡片当前的 `revision`，因此来自另一个标签页或对 `settings.yaml` 的外部编辑所产生的并发写入会以 `settings-conflict` 被拒绝；settings 提交成功后，卡片会在存储凭据前采用响应返回的脱敏用户子树与 revision，因此凭据阶段失败时，重试只会重复该阶段。删除操作只会在 profile 指向页面派生的 `<ROUTE>_API_KEY` 目标时清除已配置且可写的凭据，随后取消设置 profile；两项操作都具备幂等性，部分失败会停留在点名目标的确认对话框中供重试。环境凭据、自定义引用和无法识别目标的凭据保持不变。页面加载完成后会在推送的失效事件（`settings/changed`、`credentials/changed`、`models/changed` 与 `connection/reset`）上重拉，因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。
+每一次编辑都以 `settings.mutate` 的路径 op 落到已存分节上——每个变更字段一条 set、每个清空字段一条 unset、删除提供方行则是单独一条 unset。页面自始至终只持有**脱敏后**的 descriptor，因此它只修改自己看得见的字段，而不重建分节。DeepSeek 的 `models` 是一个按值整体替换的数组：编辑器会显示继承而来的生效模型行，直到第一次模型编辑将完整数组具化到用户层；重置则会取消该覆盖。每个模型行承载模型 ID 与显示名称，其上下文窗口与最大输出 token 数则收在该行自己的折叠区里，与 pi-ai 提供方表单采用的形态相同。两项容量都按数值键入，可带十进制的 `K` 或 `M` 后缀（`256K`、`1M`；`1M` 即 1000K），存储为纯数值，回显时写成能够往返的最短形式。空 ID、重复 ID、显式填写的空名称，以及无法读取、非正数或非整数的容量都会在写入前失败。键入的 API 密钥同样在它自己的字段上被判定：trim 之后必须非空，且每个字符都是可打印 ASCII（`[\x21-\x7E]`）——这正是 HTTP 标头值所能承载的范围，是 `@deepseek-ai/dsh-llm` 中 `normalizeApiKey` 的孪生体，因源码平面分割禁止直接引入而在此镜像。形如整行粘贴的 `NAME=value` 环境变量或首尾成对引号包裹的值，会以同一条格式失败被拒绝；该粘贴形状启发式只在浏览器中运行，因为 resolver 中的一次误判会连带让环境变量这条路也拒绝该密钥。只含空白的输入框会失败而不是被静默丢弃；留空则完全不是失败：在编辑卡片上意味着保持已存储的密钥，在新建卡片上则意味着以其他方式鉴权。被拒绝的密钥会同时拦截写入与端点探测，因此页面不会白花一次往返去换取字段上已经写明的答案。每次 settings 写入都携带卡片当前的 `revision`，因此来自另一个标签页或对 `settings.yaml` 的外部编辑所产生的并发写入会以 `settings-conflict` 被拒绝；settings 提交成功后，卡片会在存储凭据前采用响应返回的脱敏用户子树与 revision，因此凭据阶段失败时，重试只会重复该阶段。删除操作只会在 profile 指向页面派生的 `<ROUTE>_API_KEY` 目标时清除已配置且可写的凭据，随后取消设置 profile；两项操作都具备幂等性，部分失败会停留在点名目标的确认对话框中供重试。环境凭据、自定义引用和无法识别目标的凭据保持不变。页面加载完成后会在推送的失效事件（`settings/changed`、`credentials/changed`、`models/changed` 与 `connection/reset`）上重拉，因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。

 ## 模型列表与端点询问

--- a/packages/client/ui-models/src/client/ModelsSection.tsx
+++ b/packages/client/ui-models/src/client/ModelsSection.tsx
@@ -80,8 +80,8 @@ function renderProviderEditor({ target, ...props }: ProviderEditorRenderProps):
 * Remove one user-added provider and its page-managed credential. Credential
 * removal comes first so a second-step failure leaves the provider row visible
 * and the whole operation safely retryable; both unsets are idempotent.
- * The settings removal names the profile rather than rebuilding its redacted
- * namespace, which would drop literal secrets stored elsewhere.
+ * The settings removal names the profile rather than rebuilding its whole
+ * namespace from a partial view.
 * @param api - settings and credential wire faces.
 * @param controller - the page store to refresh.
 * @param target - the provider's settings address and optional managed credential.
@@ -112,16 +112,14 @@ export async function removeProviderProfile(
 }

 /**
- * Whether a whole-section provider still needs its first key: nothing marks
- * the credential configured and no literal `apiKey` is stored, so the page
- * opens the setup card instead of showing a row.
+ * Whether a whole-section provider still needs its first key: an unconfigured
+ * credential opens the setup card instead of showing a row.
 * @param row - the joined provider row.
 * @returns whether to render the setup card.
 */
 export function needsSetup(row: ProviderRow): boolean {
  if (row.entry.settingsPath.length > 0) return false
-  if (row.credential?.configured === true) return false
-  return !row.literalApiKeyConfigured
+  return row.credential?.configured !== true
 }

 function targetOf(row: ProviderRow): EditorTarget {
@@ -264,7 +262,7 @@ function Loaded({ injected }: { injected: ModelsSectionInjected }): ReactNode {
            )
          }
          const open = !adding && editing?.provider === row.entry.provider
-          const credentialConfigured = row.literalApiKeyConfigured || row.credential?.configured === true
+          const credentialConfigured = row.credential?.configured === true
          const credentialMissing = !credentialConfigured
            && row.apiKeyEnv !== undefined
            && row.credential?.configured === false
--- a/packages/client/ui-models/src/client/ProviderEditor.tsx
+++ b/packages/client/ui-models/src/client/ProviderEditor.tsx
@@ -14,9 +14,8 @@
 * model picker offers each model its own levels; `settings.yaml` keeps the
 * profile field for a deployment that knows its route. Everything else stays
 * owned by `settings.yaml`. Profile edits land as minimal `settings.mutate`
- * path ops against the stored section — the card reads the redacted
- * descriptor, so it names only the fields it can see and a stored literal
- * secret is never collaterally removed.
+ * path ops against the stored section — the card names only the fields it can
+ * see instead of rebuilding the whole subtree from a partial descriptor.
 */

 import { useEffect, useMemo, useState } from 'react'
@@ -72,10 +71,9 @@ function draftAt(namespace: SettingsNamespaceView, path: readonly string[]): Rec

 /**
 * The minimal path ops carrying `after` over `before`, both as the card sees
- * them (that is, redacted). Only keys the card observed are named: a stored
- * `role('secret')` field appears in neither side, so it produces no op and
- * survives the write — the whole reason edits are path-addressed rather than
- * a rebuilt section.
+ * them. Only keys the card observed are named; fields absent from both sides
+ * produce no op, which is why edits are path-addressed rather than a rebuilt
+ * section.
 * @param base - path of the edited subtree inside the user section.
 * @param before - the subtree as loaded, or undefined when it is new.
 * @param after - the subtree as edited.
@@ -197,9 +195,8 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
  /**
   * The write for this card, or a failure message. Every edit travels as
   * path ops against the STORED section: the draft comes from the redacted
-   * descriptor, so a wholesale replace rebuilt from it would delete the
-   * literal secrets the wire never returned. Ops name only the fields this
-   * card can see, so a stored secret is untouched by construction.
+   * descriptor, so a wholesale replace rebuilt from it could delete fields
+   * outside the card. Ops name only the fields this card can see.
   */
  const applyOnce = async (): Promise<string | undefined> => {
    const ns = namespace.ns
--- a/packages/client/ui-models/src/client/store.ts
+++ b/packages/client/ui-models/src/client/store.ts
@@ -31,8 +31,6 @@ export interface ProviderRow {
  apiKeyEnv: string | undefined
  /** Credential state for {@link apiKeyEnv}, once described. */
  credential: CredentialView | undefined
-  /** Whether the redacted secret sidecar reports an effective literal `apiKey`. */
-  literalApiKeyConfigured: boolean
 }

 /** Page snapshot. */
@@ -97,19 +95,6 @@ function apiKeyEnvOf(namespace: SettingsNamespaceView | undefined, path: readonl
  return typeof ref === 'string' && ref.length > 0 ? ref : undefined
 }

-/** Whether one namespace's redacted sidecar reports a set literal API key. */
-function literalApiKeyConfigured(
-  namespace: SettingsNamespaceView | undefined,
-  path: readonly string[],
-): boolean {
-  if (namespace === undefined) return false
-  const secretPath = [...path, 'apiKey']
-  return namespace.secrets.some(secret =>
-    secret.set
-    && secret.path.length === secretPath.length
-    && secret.path.every((key, index) => key === secretPath[index]))
-}
-
 /** The models settings page controller (one per settings surface). */
 export class ModelsSettingsStore {
  /** The snapshot the section renders from (uSES-safe store). */
@@ -170,7 +155,6 @@ export class ModelsSettingsStore {
        removable,
        apiKeyEnv: apiKeyEnvOf(namespace, entry.settingsPath),
        credential: undefined,
-        literalApiKeyConfigured: literalApiKeyConfigured(namespace, entry.settingsPath),
      }
    })
    const refs = [...new Set(rows.flatMap(row => row.apiKeyEnv === undefined ? [] : [row.apiKeyEnv]))]
@@ -257,7 +241,6 @@ export function deepSeekReadiness(state: ModelsSettingsState): DeepSeekReadiness
      reason: 'settings-unavailable',
    }
  }
-  if (row.literalApiKeyConfigured) return { kind: 'configured' }
  if (row.apiKeyEnv === undefined) {
    return {
      kind: 'unavailable',
--- a/packages/client/ui-models/tests/components.spec.tsx
+++ b/packages/client/ui-models/tests/components.spec.tsx
@@ -35,9 +35,7 @@ function capacityInputs(label: string): HTMLInputElement[] {
 }

 const PiAiConfig = Schema.object({
-  token: Schema.string().role('secret'),
  providers: Schema.dict(Schema.object({
-    apiKey: Schema.string().role('secret'),
    apiKeyEnv: Schema.string().role('credential-ref'),
    baseURL: Schema.string(),
    reasoning: Schema.union(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']),
@@ -46,7 +44,6 @@ const PiAiConfig = Schema.object({
 })

 const DeepSeekConfig = Schema.object({
-  apiKey: Schema.string().role('secret'),
  apiKeyEnv: Schema.string().role('credential-ref'),
  baseURL: Schema.string().pattern(/^https:\/\//),
  reasoningEffort: Schema.union(['off', 'high', 'max']),
@@ -99,7 +96,7 @@ function wireNamespaces(): SettingsNamespaceView[] {
      base: { defaultContextWindow: 1_000_000, maxTokens: 256_000, models: DEFAULT_DEEPSEEK_MODELS },
      user: { baseURL: 'https://base' },
      applies: 'live',
-      secrets: [{ path: ['apiKey'], set: false }],
+      secrets: [],
      revision: 0,
    },
    {
@@ -118,7 +115,7 @@ function wireNamespaces(): SettingsNamespaceView[] {
      value: { providers: { openai: { apiKeyEnv: 'OPENAI_API_KEY', baseURL: 'https://proxy', headers: { 'X-Team': 'a' } }, zombie: {} } },
      user: { providers: { openai: { apiKeyEnv: 'OPENAI_API_KEY', baseURL: 'https://proxy', headers: { 'X-Team': 'a' } }, zombie: {} } },
      applies: 'live',
-      secrets: [{ path: ['token'], set: false }, { path: ['providers', 'openai', 'apiKey'], set: false }],
+      secrets: [],
      revision: 0,
    },
  ]
@@ -262,22 +259,17 @@ describe('ModelsSection', () => {
    expect(screen.queryByLabelText(en.keyInput)).toBeNull()
  })

-  it('decides setup need from the joined credential state and literal-key sidecar', () => {
+  it('decides setup need from the joined credential state', () => {
    const entry = { provider: 'p', displayName: 'p', settingsNs: 'llm-deepseek', settingsPath: [], active: true }
-    const row = (
-      credential: ProviderRow['credential'],
-      literalApiKeyConfigured = false,
-    ): ProviderRow => ({
+    const row = (credential: ProviderRow['credential']): ProviderRow => ({
      entry,
      configured: true,
      removable: false,
      apiKeyEnv: 'X',
      credential,
-      literalApiKeyConfigured,
    })
    expect(needsSetup(row(undefined))).toBe(true)
    expect(needsSetup(row({ configured: true, writable: true }))).toBe(false)
-    expect(needsSetup(row(undefined, true))).toBe(false)
    const nested = { ...row(undefined), entry: { ...entry, settingsPath: ['providers', 'x'] } }
    expect(needsSetup(nested)).toBe(false)
  })
@@ -294,9 +286,7 @@ describe('ModelsSection', () => {
    expect(providerTargetLabel(OPENAI_TARGET)).toBe('openai')
  })

-  it('names only the fields the card can see, so an unseen secret survives', () => {
-    // `before` is the REDACTED subtree: a stored literal apiKey is in neither
-    // side, so no op mentions it and the seam leaves it alone.
+  it('names only changed fields instead of rebuilding the section', () => {
    expect(pathOps(['providers', 'openai'], { baseURL: 'https://old', reasoning: 'high' }, { reasoning: 'high' }))
      .toEqual([{ op: 'unset', path: ['providers', 'openai', 'baseURL'] }])
    expect(pathOps([], { b: 1 }, { b: 2, d: 3 }))
@@ -724,8 +714,7 @@ describe('ModelsSection', () => {
  })

  it('clears an inherited override with an unset op, never a whole-section replace', async () => {
-    // The data-loss shape: the old path rebuilt the section from the REDACTED
-    // user layer and replaced it wholesale, deleting any stored literal key.
+    // The old path rebuilt the whole user section to clear one inherited field.
    const { replace, update, mutate } = await mountSection()
    fireEvent.click(screen.getByText(en.customized))
    const url = screen.getByLabelText<HTMLInputElement>(en.baseUrl)
@@ -798,9 +787,7 @@ describe('ModelsSection', () => {
    fireEvent.click(screen.getAllByText(en.apply)[1] as HTMLElement)
    await waitFor(() => { expect(mutate).toHaveBeenCalledTimes(1) })
    // Only the edited field travels: apiKeyEnv and headers were already stored
-    // with these values, so no op restates them — and the profile's stored
-    // literal apiKey, absent from the redacted view the card read, is named by
-    // nothing at all.
+    // with these values, so no op restates them.
    expect(mutate.mock.calls[0]?.[0]).toEqual({
      ns: 'llm-pi-ai',
      ops: [{ op: 'set', path: ['providers', 'openai', 'baseURL'], value: 'https://proxy/v2' }],
@@ -1132,8 +1119,8 @@ describe('ModelsSection', () => {
  })

  it('removes by unsetting the profile path, never by rebuilding the section', async () => {
-    // The section rebuild is what dropped stored literal secrets: this page
-    // only ever holds the redacted descriptor, so the removal names the path.
+    // The page only needs to name the profile path; rebuilding the section
+    // would widen the write for no benefit.
    const { face, mutate, replace, controller } = await mountSection()
    await removeProviderProfile(
      face as unknown as Parameters<typeof removeProviderProfile>[0],
--- a/packages/client/ui-models/tests/onboarding-dialog.spec.tsx
+++ b/packages/client/ui-models/tests/onboarding-dialog.spec.tsx
@@ -28,7 +28,6 @@ function harness(options: {
  providerActive?: boolean
  settingsNamespace?: boolean
  apiKeyEnv?: string | null
-  literal?: boolean
  configured?: () => boolean
  credential?: { source?: string; writable: boolean }
  describeFailure?: string
@@ -66,7 +65,7 @@ function harness(options: {
              ? {}
              : { apiKeyEnv: options.apiKeyEnv ?? 'DEEPSEEK_API_KEY' },
            applies: 'live' as const,
-            secrets: [{ path: ['apiKey'], set: options.literal === true }],
+            secrets: [],
            revision: 0,
          }],
      })),
@@ -153,11 +152,10 @@ describe('DeepSeekOnboardingDialog', () => {
    }
  })

-  it('skips an absent adapter and already-configured literal or environment credentials', async () => {
+  it('skips an absent adapter and an already-configured environment credential', async () => {
    for (const h of [
      harness({ provider: false }),
      harness({ providerSettingsNs: '' }),
-      harness({ literal: true, describeFailure: 'credential seam absent' }),
      harness({ configured: () => true, credential: { source: 'env', writable: false } }),
    ]) {
      const view = render(<DeepSeekOnboardingDialog {...h.props} />)
--- a/packages/client/ui-models/tests/readiness.spec.ts
+++ b/packages/client/ui-models/tests/readiness.spec.ts
@@ -19,7 +19,6 @@ function row(overrides: Partial<ProviderRow> = {}): ProviderRow {
    removable: false,
    apiKeyEnv: 'DEEPSEEK_API_KEY',
    credential: missingCredential,
-    literalApiKeyConfigured: false,
    ...overrides,
  }
 }
@@ -64,13 +63,6 @@ describe('deepSeekReadiness', () => {
    }))).toEqual({ kind: 'configured' })
  })

-  it('accepts the redacted literal-key sidecar before judging the credential domain', () => {
-    expect(deepSeekReadiness(state({
-      credentialError: 'credentials service absent',
-      rows: [row({ literalApiKeyConfigured: true, credential: undefined })],
-    }))).toEqual({ kind: 'configured' })
-  })
-
  it('turns missing capabilities and inconsistent descriptors into diagnostics', () => {
    expect(deepSeekReadiness(state({ status: 'error', error: 'settings down' }))).toEqual({
      kind: 'unavailable',
--- a/packages/client/ui-models/tests/store.spec.ts
+++ b/packages/client/ui-models/tests/store.spec.ts
@@ -25,7 +25,7 @@ const NAMESPACES = [
    value: { apiKeyEnv: 'DEEPSEEK_API_KEY', baseURL: 'https://base' },
    base: { baseURL: 'https://base' },
    applies: 'live' as const,
-    secrets: [{ path: ['apiKey'], set: false }],
+    secrets: [],
    revision: 0,
  },
  {
@@ -85,7 +85,6 @@ describe('ModelsSettingsStore', () => {
      removable: false,
      apiKeyEnv: 'DEEPSEEK_API_KEY',
      credential: { configured: false, writable: true },
-      literalApiKeyConfigured: false,
    })
    expect(byProvider.get('openai')).toMatchObject({
      configured: true,
@@ -131,30 +130,6 @@ describe('ModelsSettingsStore', () => {
    expect(store.store.getSnapshot().credentialError).toBe('credential transport refusal')
  })

-  it('joins a configured literal key from the redacted secret sidecar', async () => {
-    const { face } = api({
-      describeSettings: () => Promise.resolve(ok({
-        writable: true,
-        hasDocument: false,
-        namespaces: [{
-          ...NAMESPACES[0],
-          secrets: [
-            { path: ['apiKey', 'nested'], set: true },
-            { path: ['different'], set: true },
-            { path: ['apiKey'], set: true },
-          ],
-        }] as never,
-      })),
-      providers: () => Promise.resolve(ok({ providers: [DIRECTORY[0]] as never })),
-    })
-    const store = new ModelsSettingsStore(face)
-    await store.load()
-    expect(store.store.getSnapshot().rows[0]).toMatchObject({
-      literalApiKeyConfigured: true,
-      apiKeyEnv: 'DEEPSEEK_API_KEY',
-    })
-  })
-
  it('surfaces a directory failure and keeps the last good rows', async () => {
    const { face } = api()
    const store = new ModelsSettingsStore(face)
--- a/packages/client/ui-primitives/tsdown.config.ts
+++ b/packages/client/ui-primitives/tsdown.config.ts
@@ -1,4 +1,4 @@
-import { defineConfig } from 'tsdown'
+import { clientOnly } from '../tsdown.client.ts'

 /**
 * ui-primitives is browser-only, but its lib bundle IS imported under plain
@@ -8,7 +8,7 @@ import { defineConfig } from 'tsdown'
 * (loader module table / vite source paths), which compile src directly and
 * never read lib.
 */
-export default defineConfig({
+export default clientOnly([{
  entry: ['lib/types/index.js', 'lib/types/invariant.js'],
  outDir: 'lib',
  format: ['esm'],
@@ -28,4 +28,4 @@ export default defineConfig({
      return 'export default {};'
    },
  }],
-})
+}])
--- 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: f70bd2780f255cd8e0c64acb3da3863e10c4fa9d
-README.zh.md: 6eb6cbd3ae196a540e161a3a23f9df2136824f2e
+README.md: bdd772662acda1f8cf1b7d8a7c5532f9b37123dd
+README.zh.md: 959ff0ede6d545150fb22710c8af75859966caa9
--- a/packages/client/ui-skill/README.md
+++ b/packages/client/ui-skill/README.md
@@ -2,7 +2,9 @@

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

-Skill reference 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 returns the intersection of model-invocable and user-invocable skills because this browser path inserts a model reference rather than loading the body directly. 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)`; picking a candidate lands the literal `/name ` text through the slash pipeline (decision 21 plain-text reference), and the source `codec` owns the reference's two projections: `clipboardText` → `/name`, `serialize` → the model form `<skill>name</skill>` invoked at submit time. The RPC rides the plugin's root-context connection captured at registration — the source never reads services off a per-call argument. The source implements no `matchSpace`/`matchEnter` hooks — skill references never enter command adjudication and ride ordinary prompts into the default sink.
+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 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.

@@ -14,23 +16,22 @@ The browser plugin also registers a keyed `skill` toolview in `conversation.chat

 ## Model Experience

-### Skill reference text in the user prompt
+### User-explicit skill invocation

 #### What the model sees

-A picked candidate lands the literal `/name ` in the draft (decision 21: plain text, no `<skill>` tag); the text reaches the model verbatim inside the ordinary user message (`session.prompt`), with no dedicated content block, prompt section, or host-side expansion. The association with the actual skill is model-side and non-deterministic: the session prefix already carries the skill catalog (rendered by `dsh-tool-skill`), and the reference's name matching a catalog entry is what invites the model to load it.
+The user's message reaches the model verbatim, `/name` literal included. The host's pre-step boundary (`dsh-tool-skill`) then appends the canonical `<skill_content>` block — the same `renderSkillContent` output the `skill` tool returns — as injected instructions context at the end of that step's injections, closest to the model's answer. Loading is deterministic: the model receives the full body without being asked to call the `skill` tool, and the catalog tells it not to re-load an inline-injected skill.

 #### Token effect

-Conditional and tiny: only a pick (or hand-typing the same text) adds the reference's characters to that one user message. Menu browsing and the candidate fetch add zero model tokens.
+One invocation adds the rendered skill body to that turn as injected context — the same cost as the model loading the skill through the tool, paid unconditionally instead of at the model's discretion. Menu browsing and the candidate fetch add zero model tokens.

 #### KV Cache effect

-Append-only: the reference is part of a new user message appended after the reusable history prefix. This package never edits earlier request tokens.
+Append-only: the injected message lands after the reusable history prefix. This package never edits earlier request tokens.

 ## Known Limitations and Deferred Work

 - **Result-only history pages use the generic row** — keyed dispatch needs the paired call in the runtime window; pagination that leaves the call outside has no tool identity. This client presentation feature does not extend the history wire contract to recover it.
- **Non-deterministic skill loading** — the reference is a collaboration cue, not a guarantee; the model may ignore it. The rework path when hit rate proves insufficient (a host-side `context/skill-reference` guidance package, or full-text injection) sits in the design ledger; the wire text shape would not change.
- **First keystroke may race the prewarm** — the scope-birth warm launches the catalog fetch, but a menu opened before it settles shows no skill candidates for that keystroke. Accepted by design: skill references do not participate in enter adjudication, so nothing correctness-bearing waits on the catalog.
- **Text is the truth** — the reference is plain draft text; a hand-typed identical token is the same reference. Chip visuals derive from the lexicon scan; no occurrence identity or position tracking (componentized chips are a ledger item).
+- **Text is the truth** — the reference is plain draft text; a hand-typed identical token is the same reference, and the host gesture boundary judges the sent text, not the menu interaction. Chip visuals derive from the lexicon scan; no occurrence identity, position tracking, or structured reference payload on the prompt wire (both are ledger items).
+- **A menu opened before the prewarm settles** shows no skill candidates for that keystroke; the next keystroke re-polls the settled cache.
--- a/packages/client/ui-skill/README.zh.md
+++ b/packages/client/ui-skill/README.zh.md
@@ -2,7 +2,9 @@

 [English](README.md) | 中文

-skill（技能）引用 source 的浏览器端：把 `/` 触发的 `skill` source 注册进 `ctx.slash`。普通会话的候选来自 `skill.list` RPC，以每次调用的 `ClientSessionContext` 投影中的 `{sessionId}` 寻址，host 从会话 header 解析 `cwd`。宿主返回模型可调用与用户可调用 skill 的交集，因为该浏览器路径插入的是模型引用，而不是直接加载正文。由目录寻址的可继续 subagent 在客户端解析为没有 skill 候选，因为现有 skill RPC 要求会话已挂载；查看其持久化历史不得激活它。目录按普通会话缓存，拉取走 single-flight；scope 创建时的 `warm` 钩子预热该会话的缓存项，`connection/reset` 清空全部缓存。结果按 `startsWith(query)` 过滤；pick 一个候选会把字面文本 `/name ` 经 slash 流水线落进草稿（决策 21 的纯文本引用），source 的 `codec` 拥有该引用的两种投影：`clipboardText` → `/name`，`serialize` → 提交时生成的模型形式 `<skill>name</skill>`。RPC 使用插件注册时捕获的根上下文连接——source 绝不从每次调用的参数上读取服务。source 不实现 `matchSpace`／`matchEnter` 钩子——skill 引用永不进入命令裁决，随普通提示词落入 default sink。
+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` 扫描派生。

 `skill.list` 失败时 `candidates` 抛出异常，slash 壳层记录日志并折叠为静默的菜单组丢弃——菜单只显示 pending／ready 状态。

@@ -14,23 +16,22 @@ skill（技能）引用 source 的浏览器端：把 `/` 触发的 `skill` sourc

 ## 模型体验

-### 用户提示词中的 skill 引用文本
+### 用户显式 skill 调用

 #### 模型看到的内容

-被 pick 的候选会把字面文本 `/name ` 落进草稿（决策 21：纯文本，无 `<skill>` 标签）；该文本原样进入普通用户消息（`session.prompt`）到达模型，没有专用内容块、提示词 section 或 host 侧展开。与实际 skill 的关联在模型侧建立且具有非确定性：会话前缀已携带 skill 目录（由 `dsh-tool-skill` 渲染），引用名称与目录条目匹配，正是这一点引导模型去加载它。
+用户消息原样到达模型，字面文本 `/name` 也包含在内。随后宿主的 pre-step 边界（`dsh-tool-skill`）把规范的 `<skill_content>` 块——与 `skill` 工具返回的 `renderSkillContent` 输出相同——作为注入的指令上下文追加在该步骤各项注入的末尾，最贴近模型的回答。加载是确定性的：模型无需被要求调用 `skill` 工具就能收到完整正文，目录也会告诉它不要重新加载已内联注入的 skill。

 #### Token 影响

-有条件且极小：只有 pick（或手动键入相同文本）会把引用的字符加进那一条用户消息。浏览菜单和拉取候选不会增加任何模型 token。
+一次调用会把渲染后的 skill 正文作为注入上下文加进该轮次——成本与模型经由工具加载该 skill 相同，只是无条件支付，而非由模型自行裁量。浏览菜单和拉取候选不会增加任何模型 token。

 #### KV Cache 影响

-仅追加：引用是追加在可复用历史前缀之后的新用户消息的一部分。该包绝不改写较早的请求 token。
+仅追加：注入的消息落在可复用历史前缀之后。该包绝不改写较早的请求 token。

 ## 已知限制与暂缓事项

 - **仅含结果的 history 页使用通用行**：键控分派要求配对调用位于 runtime 窗口内；分页将调用留在窗口外时，结果没有工具身份。这项客户端呈现功能不会为了恢复该身份而扩展 history 协议契约。
- **skill 加载具有非确定性**：引用是协作线索，不是保证；模型可能忽略它。针对命中率不足情况的返工路径（host 侧 `context/skill-reference` 引导包，或全文注入）记录在设计台账中；协议中的文本形态不会改变。
- **首次击键可能与预热竞速**：scope 创建时的预热会启动目录拉取，但目录落定之前打开的菜单，在那次击键下不会显示 skill 候选。这是设计上接受的取舍：skill 引用不参与回车裁决，因此没有任何攸关正确性的环节等待目录。
- **文本是唯一依据**：引用是普通的草稿文本；手动键入的相同 token 就是同一个引用。chip 视觉由 lexicon 扫描派生；没有 occurrence 身份或位置跟踪（组件化 chip 是台账事项）。
+- **文本是唯一依据**：引用是普通的草稿文本；手动键入的相同 token 就是同一个引用，宿主手势边界评判的是发出的文本，而不是菜单交互。chip 视觉由 lexicon 扫描派生；没有 occurrence 身份、位置跟踪，也没有提示词协议上的结构化引用载荷（两者都是台账事项）。
+- **预热落定之前打开的菜单**：在那次击键下不显示 skill 候选；下一次击键会重新轮询已落定的缓存。
--- a/packages/client/ui-skill/src/client/index.ts
+++ b/packages/client/ui-skill/src/client/index.ts
@@ -2,13 +2,16 @@
 * Skill reference plugin, browser half: registers the '/' skill source —
 * 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), pick inserts the literal `/name `
- * text (decision 21: the draft carries plain text, chip visuals are derived
- * by scanning against the source lexicon, and the prompt ships the same
- * literal — no `<skill>` tag). The RPC rides the plugin's root-context
- * connection captured at registration — the source never reads services off
- * a per-call argument. No adjudication hooks: skill references ride
- * ordinary prompts and never enter command adjudication.
+ * resolves cwd from the session header). A pick lands the literal `/name `
+ * text and the prompt ships the same literal (decision 21); 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).
 *
 * Catalog fetches are cached per session (the small twin of the ui-command
 * directory): the per-keystroke candidates re-poll filters a settled
@@ -119,6 +122,10 @@ export function apply(ctx: ClientContext): void {
    for (const key of [...fetches.keys()]) invalidate(key)
  }

+  // The bound translate resolves against the registered dictionaries with the
+  // locale service's own fallback ladder; candidate-time reads stay plain text.
+  const t = ctx.locale.bind(NS)
+
  const source: SlashSource = {
    trigger: '/',
    name: 'skill',
@@ -129,7 +136,12 @@ export function apply(ctx: ClientContext): void {
      if (signal.aborted) return []
      return skills
        .filter(skill => skill.name.startsWith(query))
-        .map(skill => ({ name: skill.name, description: skill.description }))
+        .map(skill => ({
+          name: skill.name,
+          // The user-only marker rides the description (the menu's only
+          // secondary text); `hint` is the claim-state ghost text, not a badge.
+          description: skill.modelInvocable ? skill.description : `${t('menu.userOnly')} · ${skill.description}`,
+        }))
    },
    warm(session) {
      // Fire-and-forget scope-birth prewarm; the shared fetch reports
@@ -150,16 +162,14 @@ export function apply(ctx: ClientContext): void {
      }
    },
    onPick({ candidate }) {
-      // Decision 21: 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: 'skill', ref: candidate.name, label: candidate.name, clipboardText: `/${candidate.name}` } }
+      // Decision 21: the pick lands plain text and the prompt ships the same
+      // literal. Determinism no longer rides the client — 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
+      // line client-side before it ever becomes a prompt.
      return { text: `/${candidate.name} ` }
    },
-    codec: {
-      clipboardText: ref => `/${ref}`,
-      serialize: ref => Promise.resolve(`<skill>${ref}</skill>`),
-    },
  }
  const slash = ctx.get('slash') as SlashServiceContract
  ctx.on('connection/reset', clearAll)
--- a/packages/client/ui-skill/src/client/locales.ts
+++ b/packages/client/ui-skill/src/client/locales.ts
@@ -9,6 +9,7 @@ export const zh = {
  'row.failed': 'skill 加载失败',
  'row.stopped': 'skill 加载已中止',
  'row.instructions': '说明',
+  'menu.userOnly': '仅用户',
 } satisfies Record<string, string>

 /** The skill namespace key union. */
@@ -20,4 +21,5 @@ export const en = {
  'row.failed': 'Skill load failed',
  'row.stopped': 'Skill load stopped',
  'row.instructions': 'Instructions',
+  'menu.userOnly': 'user-only',
 } satisfies Record<SkillKey, string>
--- a/packages/client/ui-skill/tests/browser-plugin.spec.ts
+++ b/packages/client/ui-skill/tests/browser-plugin.spec.ts
@@ -20,11 +20,15 @@ import type { ClientSessionContext, SlashSource } from '@deepseek-ai/dsh-client-
 import { apply, inject } from '../src/client/index.ts'
 import { SkillRow as SkillToolRow } from '../src/client/SkillRow.tsx'

-type SkillRow = { name: string; description: string; whenToUse?: string }
+type SkillRow = { name: string; description: string; whenToUse?: string; modelInvocable?: boolean }
 type ListResult =
  | { ok: true; value: { skills: SkillRow[] } }
  | { ok: false; error: { code: string; message: string; details: object } }
 type ListFn = (payload: object, signal?: AbortSignal) => Promise<{ result: ListResult }>
+type InvokeResult =
+  | { ok: true; value: { accepted: true } }
+  | { ok: false; error: { code: string; message: string; details: object } }
+type InvokeFn = (payload: object) => Promise<{ result: InvokeResult }>

 interface PresentationCapture {
  slots: SlotsService
@@ -49,16 +53,19 @@ function providePresentation(ctx: Context): PresentationCapture {
      capture.dictionaries.push({ namespace, dictionaries })
      return () => { capture.localeDisposed = true }
    },
+    // Minimal bound-translate fake: zh dictionary lookup, key passthrough on miss.
+    bind: () => (key: string) => key === 'menu.userOnly' ? '仅用户' : key,
  })
  return capture
 }

 /** Boot the plugin over fake slash/connection faces; returns the captured source and its ctx. */
-async function bench(list: ListFn, addressed?: SessionId) {
+async function bench(list: ListFn, addressed?: SessionId, invoke?: InvokeFn) {
  const ctx = new Context()
  let captured: SlashSource | undefined
  ctx.provide('slash', { registerSource: (src: SlashSource) => { captured = src; return () => {} } })
-  ctx.provide('connection', { api: { skills: { list } } })
+  const defaultInvoke: InvokeFn = () => Promise.resolve({ result: { ok: true as const, value: { accepted: true as const } } })
+  ctx.provide('connection', { api: { skills: { list, invoke: invoke ?? defaultInvoke } } })
  ctx.provide('sessions', {
    subagentAddress: (id: SessionId) => id === addressed
      ? { parentSessionId: sid('parent'), childSessionId: id, mode: 'continuable' as const }
@@ -70,9 +77,9 @@ async function bench(list: ListFn, addressed?: SessionId) {
 }

 const CATALOG: SkillRow[] = [
-  { name: 'commit-helper', description: 'commit flow' },
-  { name: 'code-review', description: 'review flow', whenToUse: 'reviews' },
-  { name: 'deploy', description: 'deploy flow' },
+  { name: 'commit-helper', description: 'commit flow', modelInvocable: true },
+  { name: 'code-review', description: 'review flow', whenToUse: 'reviews', modelInvocable: true },
+  { name: 'deploy', description: 'deploy flow', modelInvocable: true },
 ]

 const listOk = (skills: SkillRow[]): ListFn => () => Promise.resolve({ result: { ok: true as const, value: { skills } } })
@@ -117,12 +124,14 @@ describe('apply', () => {
          'row.failed': 'skill 加载失败',
          'row.stopped': 'skill 加载已中止',
          'row.instructions': '说明',
+          'menu.userOnly': '仅用户',
        },
        en: {
          'row.running': 'Loading skill',
          'row.failed': 'Skill load failed',
          'row.stopped': 'Skill load stopped',
          'row.instructions': 'Instructions',
+          'menu.userOnly': 'user-only',
        },
      },
    }])
@@ -313,8 +322,8 @@ describe('lexicon', () => {
  })
 })

-describe('pick and codec', () => {
-  it('onPick returns the literal /name text with a closing space (decision 21)', async () => {
+describe('pick lands plain text (decision 21)', () => {
+  it('onPick returns the literal /name text with a closing space', async () => {
    const { source } = await bench(listOk(CATALOG))
    const outcome = source.onPick({
      candidate: { name: 'commit-helper', description: 'commit flow' },
@@ -326,18 +335,27 @@ describe('pick and codec', () => {
    expect(outcome).toEqual({ text: '/commit-helper ' })
  })

-  it('codec projects clipboard `/name` and serializes the model form <skill>name</skill>', async () => {
-    const { source } = await bench(listOk(CATALOG))
-    expect(source.codec!.clipboardText('deploy')).toBe('/deploy')
-    await expect(source.codec!.serialize('deploy', new AbortController().signal))
-      .resolves.toBe('<skill>deploy</skill>')
-  })
-})
-
-describe('adjudication', () => {
-  it('never participates: no matchSpace/matchEnter hooks on the skill source', async () => {
+  it('keeps the legacy reference codec removed and stays out of adjudication', async () => {
    const { source } = await bench(listOk(CATALOG))
+    // Determinism lives host-side (the pre-step gesture boundary), so the
+    // source neither claims lines nor serializes reference markup.
+    expect(source.codec).toBeUndefined()
    expect(typeof source.matchSpace).toBe('undefined')
    expect(typeof source.matchEnter).toBe('undefined')
  })
 })
+
+describe('user-only marking', () => {
+  it('prefixes the description of candidates the model cannot invoke', async () => {
+    const rows: SkillRow[] = [
+      { name: 'shared-skill', description: 'both surfaces', modelInvocable: true },
+      { name: 'user-only-skill', description: 'user surface only', modelInvocable: false },
+    ]
+    const { source } = await bench(listOk(rows))
+    const candidates = await source.candidates(proj('s1'), req(''))
+    expect(candidates).toEqual([
+      { name: 'shared-skill', description: 'both surfaces' },
+      { name: 'user-only-skill', description: '仅用户 · user surface only' },
+    ])
+  })
+})
--- a/packages/client/ui-slots/tsdown.config.ts
+++ b/packages/client/ui-slots/tsdown.config.ts
@@ -0,0 +1,6 @@
+import { clientLibrary } from '../tsdown.client.ts'
+
+export default clientLibrary(
+  '@deepseek-ai/dsh-client-ui-slots',
+  ['lib/types/index.js', 'lib/types/invariant.js'],
+)
--- a/packages/client/ui-subagent/src/client/SubagentCatalogAction.tsx
+++ b/packages/client/ui-subagent/src/client/SubagentCatalogAction.tsx
@@ -1,9 +1,9 @@
 import {
-  useEffect, useRef, useState, type KeyboardEvent, type MouseEvent,
+  useEffect, useMemo, useRef, useState, type KeyboardEvent, type MouseEvent,
 } from 'react'
-import type {
-  SessionId, SessionListState, SessionProjectionMap, SessionSummary, SubagentAddress,
-  SubagentCatalogSnapshot,
+import {
+  indexSubagentDescendants, type SessionId, type SessionListState, type SessionProjectionMap,
+  type SessionSummary, type SubagentAddress, type SubagentCatalogSnapshot,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import {
  IconChevronDownOutline14, IconChevronRightOutline14, IconRefreshOutline14, StateDot,
@@ -171,30 +171,7 @@ function formatExactDuration(ms: number, t: TranslateNS<typeof NS>): string {
    })
 }

-/** Aggregate the complete subagent-only descendant subtree from flat summaries. */
-function summarizeDescendants(
-  sessionId: SessionId,
-  summaries: Readonly<Record<SessionId, SessionSummary>>,
-): { count: number; running: boolean } {
-  let count = 0
-  let running = false
-  for (const summary of Object.values(summaries)) {
-    if (summary.origin !== 'subagent') continue
-    const seen = new Set<SessionId>()
-    let current: SessionSummary | undefined = summary
-    while (current?.origin === 'subagent' && current.parentId !== undefined
-      && !seen.has(current.id)) {
-      seen.add(current.id)
-      if (current.parentId === sessionId) {
-        count += 1
-        running ||= summary.running
-        break
-      }
-      current = summaries[current.parentId]
-    }
-  }
-  return { count, running }
-}
+const NO_DESCENDANTS = { count: 0, runningCount: 0 } as const

 /** Render the known direct-child shape while its authoritative catalog hydrates. */
 function CatalogLoadingRows({
@@ -448,12 +425,15 @@ export function SubagentCatalogAction({
  const setCatalogOpenRef = useRef(setCatalogOpen)
  setCatalogOpenRef.current = setCatalogOpen
  const healthy = catalog?.entries.filter(entry => entry.kind === 'child') ?? []
-  const descendants = summarizeDescendants(sessionId, summaries)
+  const descendants = useMemo(
+    () => indexSubagentDescendants(summaries).get(sessionId) ?? NO_DESCENDANTS,
+    [sessionId, summaries],
+  )
  // The catalog can arrive before the session-list baseline; never undercount
  // the already-visible direct rows during that short bootstrap window.
  const descendantCount = Math.max(healthy.length, descendants.count)
  const totalCountKey = descendantCount === 1 ? 'count.total.one' : 'count.total.other'
-  const runningCountKey = descendantCount === 1 ? 'count.running.one' : 'count.running.other'
+  const runningCountKey = descendants.runningCount === 1 ? 'count.running.one' : 'count.running.other'
  // Session summaries can announce membership before the descriptor-backed catalog catches up.
  // Keep that entry point visible through disabled loading rows; only catalog rows are navigable.
  const summaryBackedLoading = descendants.count > 0
@@ -527,10 +507,10 @@ export function SubagentCatalogAction({
  }, [open])

  useEffect(() => {
-    if (!open || !descendants.running) return
+    if (!open || descendants.runningCount === 0) return
    const timer = setInterval(() => { setNow(Date.now()) }, 1_000)
    return () => { clearInterval(timer) }
-  }, [open, descendants.running])
+  }, [open, descendants.runningCount])

  useEffect(() => () => {
    for (const parentSessionId of observedCatalogs.current) {
@@ -584,7 +564,10 @@ export function SubagentCatalogAction({
        className={css.trigger}
        aria-haspopup="tree"
        aria-expanded={open}
-        aria-label={t(descendants.running ? runningCountKey : totalCountKey, { count: descendantCount })}
+        aria-label={t(
+          descendants.runningCount > 0 ? runningCountKey : totalCountKey,
+          { count: descendants.runningCount > 0 ? descendants.runningCount : descendantCount },
+        )}
        onClick={() => { changeOpen(!open) }}
        onKeyDown={(event) => {
          if (event.key !== 'ArrowDown') return
@@ -594,7 +577,7 @@ export function SubagentCatalogAction({
        }}
      >
        <span className={css.activitySlot}>
-          {descendants.running && <StateDot state="ongoing" />}
+          {descendants.runningCount > 0 && <StateDot state="ongoing" />}
        </span>
        <span className={css.count}>{t(totalCountKey, { count: descendantCount })}</span>
        <IconChevronDownOutline14 className={open ? css.triggerOpen : undefined} />
--- a/packages/client/ui-subagent/tests/conversation-ui.spec.tsx
+++ b/packages/client/ui-subagent/tests/conversation-ui.spec.tsx
@@ -108,7 +108,7 @@ describe('SubagentCatalogAction', () => {
    }
    const view = render(<SubagentCatalogAction {...props(catalog(), {}, summaries)} />)

-    const trigger = screen.getByRole('button', { name: '3 个子代理，正在运行' })
+    const trigger = screen.getByRole('button', { name: '1 个子代理，正在运行' })
    expect(trigger.querySelector('[data-state="ongoing"]')).not.toBeNull()

    view.rerender(<SubagentCatalogAction {...props(catalog(), {}, {
@@ -322,7 +322,9 @@ describe('SubagentCatalogAction', () => {
    })) as Record<SessionId, SessionSummary>
    const input = props(catalog({ entries }), {}, summaries)
    render(<SubagentCatalogAction {...input} />)
-    fireEvent.click(screen.getByRole('button', { name: /9 个子代理/ }))
+    const trigger = screen.getByRole('button', { name: '1 个子代理，正在运行' })
+    expect(within(trigger).getByText('9 个子代理')).toBeTruthy()
+    fireEvent.click(trigger)

    const runningRow = screen.getByRole('treeitem', { name: /running.*4\.6K tok · 1分10秒/ })
    const runningMetrics = within(runningRow)
@@ -506,7 +508,8 @@ describe('SubagentCatalogAction', () => {
    const absent = props(undefined, {}, summaries)
    const view = render(<SubagentCatalogAction {...absent} />)

-    const trigger = screen.getByRole('button', { name: '2 个子代理，正在运行' })
+    const trigger = screen.getByRole('button', { name: '1 个子代理，正在运行' })
+    expect(within(trigger).getByText('2 个子代理')).toBeTruthy()
    fireEvent.click(trigger)
    expect(absent.setCatalogOpen).toHaveBeenCalledWith(PARENT, true)
    expect(screen.getAllByRole('treeitem', { name: '正在加载子代理' })).toHaveLength(2)
@@ -514,7 +517,7 @@ describe('SubagentCatalogAction', () => {

    const staleEmpty = props(catalog({ entries: [] }), {}, summaries)
    view.rerender(<SubagentCatalogAction {...staleEmpty} />)
-    expect(screen.getByRole('button', { name: '2 个子代理，正在运行' })).toBeTruthy()
+    expect(screen.getByRole('button', { name: '1 个子代理，正在运行' })).toBeTruthy()
    expect(screen.getAllByRole('treeitem', { name: '正在加载子代理' })).toHaveLength(2)
    expect(staleEmpty.openChild).not.toHaveBeenCalled()
  })
--- a/packages/client/ui-theme/tsdown.config.ts
+++ b/packages/client/ui-theme/tsdown.config.ts
@@ -1,11 +1,11 @@
 import { clientBundle } from '../tsdown.client.ts'

-const [lib, client] = clientBundle(
+export default clientBundle(
  '@deepseek-ai/dsh-client-ui-theme',
  ['lib/types/index.js', 'lib/types/invariant.js'],
+  {
+    lib: {
+      copy: [{ from: 'src/styles/*', to: 'lib/styles' }],
+    },
+  },
 )
-
-export default [{
-  ...lib,
-  copy: [{ from: 'src/styles/*', to: 'lib/styles' }],
-}, client]
--- a/packages/client/ui-trajectory/tests/layout.spec.tsx
+++ b/packages/client/ui-trajectory/tests/layout.spec.tsx
@@ -324,7 +324,10 @@ describe('deriveTrajectoryLayout', () => {
      },
      // A landed compaction renders no cell, but is still a real log position,
      // so it moves the cursor after the visible context row.
-      { kind: 'compaction', seq: 5, time: 9_500, summary: 'checkpoint facts' },
+      {
+        kind: 'compaction', seq: 5, time: 9_500, summary: 'checkpoint facts',
+        summaryEventSeq: 4, shadowedItemCount: 2, shadowedTokenCount: 100,
+      },
      {
        kind: 'assistant', seq: 6, time: 10_000, turn: 1, step: 0,
        blocks: [{ kind: 'text', text: 'done' }],
--- a/packages/client/ui-workspace/README.i18n.yaml
+++ b/packages/client/ui-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/client/ui-workspace/README.md
-README.md: bd7313b560e76378e4fff274c99bb976819aebae
-README.zh.md: 734a897b9cb9c3469d8f402b13bff4b62753f9b2
+README.md: 1ec07bd41e72bb5a26b2cfc3bf90e57e7d92db08
+README.zh.md: 18d9e356a9e5deb38624f377d41b2fc8bc677294
--- a/packages/client/ui-workspace/README.md
+++ b/packages/client/ui-workspace/README.md
@@ -16,7 +16,7 @@ Session rows render the runtime's live `pendingInteraction` classification: appr

 Both target slots are declared by other plugins, so `apply` uses `slots.inject()` to register for each declaration lifetime and re-register after a declaring slot is restored.

-The shared sidebar projection hides rows whose durable Session summary has `origin: 'subagent'`; users enter those conversations through the selected parent's subagent header catalog. Ordinary forks remain visible because lineage alone does not set that origin. The runtime keeps hidden rows available for conversation, title, and addressed transport state.
+The shared sidebar projection hides rows whose durable Session summary has `origin: 'subagent'`; users enter those conversations through the selected parent's subagent header catalog. Each visible ordinary row inherits the blue activity indicator while any descendant reached through uninterrupted subagent-origin lineage is running, and its hover and assistive text report the exact running-descendant count without describing an idle parent as running. Ordinary forks remain visible and terminate this aggregation because lineage alone does not set their origin. Pending user interaction outranks the session's own running state, and either remains the primary row status while descendant activity stays available as a separate hover and assistive status. With neither present, descendant activity outranks the green unviewed-completion reminder; the reminder returns once no descendant is running. The runtime keeps hidden rows available for conversation, title, and addressed transport state.

 ## Model Experience

--- a/packages/client/ui-workspace/README.zh.md
+++ b/packages/client/ui-workspace/README.zh.md
@@ -16,7 +16,7 @@ Session 行渲染运行时的实时 `pendingInteraction` 分类：审批显示**

 两个目标 slot 都由其他插件声明，因此 `apply` 使用 `slots.inject()` 在各自的声明生命周期内完成注册，并在目标 slot 的声明恢复后重新注册。

-共享侧边栏投影会隐藏持久化 Session 摘要中带有 `origin: 'subagent'` 的行；用户从所选 parent 的 subagent 页头目录进入这些对话。普通 fork 仍然可见，因为仅有谱系不会设置该 origin。运行时仍保留隐藏行，供对话、标题与已寻址传输状态使用。
+共享侧边栏投影会隐藏持久化 Session 摘要中带有 `origin: 'subagent'` 的行；用户从所选 parent 的 subagent 页头目录进入这些对话。每个可见的普通行都会在经不间断的 subagent 谱系可达的任一后代运行时继承蓝色活动指示器；其悬停与无障碍文本会报告确切的运行中后代数量，同时不会把空闲 parent 描述为正在运行。普通 fork 仍然可见，并会终止此聚合，因为仅有谱系不会设置该 origin。待处理的用户交互优先于会话自身的运行中状态，二者无论哪一项存在都会保持为行的主要状态，而后代活动仍作为独立的悬停与无障碍状态保留。两者均不存在时，后代活动优先于绿色的未查看完成提醒；最后一个运行中的后代停止后，该提醒会重新出现。运行时仍保留隐藏行，供对话、标题与已寻址传输状态使用。

 ## 模型体验

--- a/packages/client/ui-workspace/src/client/locales.ts
+++ b/packages/client/ui-workspace/src/client/locales.ts
@@ -45,6 +45,8 @@ export const zh = {
  'actions.session.aria': '会话“{name}”的操作',
  'actions.newSession.aria': '在“{name}”中新建会话',
  'status.running': '进行中',
+  'status.subagentsRunning.one': '{n} 个子代理运行中',
+  'status.subagentsRunning.other': '{n} 个子代理运行中',
  'status.idle': '空闲',
  'status.waitingApproval': '等待审批',
  'status.planReview': '计划待审',
@@ -106,6 +108,8 @@ export const en = {
  'actions.session.aria': 'Session actions for {name}',
  'actions.newSession.aria': 'New session in {name}',
  'status.running': 'Running',
+  'status.subagentsRunning.one': '{n} subagent running',
+  'status.subagentsRunning.other': '{n} subagents running',
  'status.idle': 'Idle',
  'status.waitingApproval': 'Waiting for approval',
  'status.planReview': 'Plan awaiting review',
--- a/packages/client/ui-workspace/src/client/rows/Rows.tsx
+++ b/packages/client/ui-workspace/src/client/rows/Rows.tsx
@@ -171,37 +171,70 @@ function assertNever(value: never): never {
  throw new Error(`unknown pending interaction: ${String(value)}`)
 }

-/** Session status presentation; pending user interaction outranks the running state. */
-function sessionStatus(
-  node: Pick<SessionNode, 'pendingInteraction' | 'running' | 'completed'>,
+interface SessionStatus {
+  state: StateDotState
+  label: string
+}
+
+/**
+ * Session status presentation; pending interaction is primary and live activity
+ * outranks completion reminders.
+ */
+function sessionStatuses(
+  node: Pick<SessionNode, 'pendingInteraction' | 'running' | 'runningSubagentCount' | 'completed'>,
  t: RowTranslate,
-): { state: StateDotState; label: string } {
+): readonly [SessionStatus, ...SessionStatus[]] {
+  const subagents: SessionStatus | undefined = node.runningSubagentCount === 0
+    ? undefined
+    : {
+      state: 'ongoing',
+      label: t(
+        node.runningSubagentCount === 1
+          ? 'status.subagentsRunning.one'
+          : 'status.subagentsRunning.other',
+        { n: node.runningSubagentCount },
+      ),
+    }
+  let pending: SessionStatus | undefined
  switch (node.pendingInteraction) {
-    case 'approval': return { state: 'warning', label: t('status.waitingApproval') }
-    case 'plan-review': return { state: 'warning', label: t('status.planReview') }
-    case 'question': return { state: 'warning', label: t('status.waitingAnswer') }
+    case 'approval':
+      pending = { state: 'warning', label: t('status.waitingApproval') }
+      break
+    case 'plan-review':
+      pending = { state: 'warning', label: t('status.planReview') }
+      break
+    case 'question':
+      pending = { state: 'warning', label: t('status.waitingAnswer') }
+      break
    case undefined: break
    /* v8 ignore next -- closed PendingInteractionStatus union */
    default: return assertNever(node.pendingInteraction)
  }
-  if (node.running) return { state: 'ongoing', label: t('status.running') }
-  if (node.completed) return { state: 'done', label: t('status.completed') }
-  return { state: 'done', label: t('status.idle') }
+  if (pending !== undefined) return subagents === undefined ? [pending] : [pending, subagents]
+  if (node.running) {
+    const primary: SessionStatus = { state: 'ongoing', label: t('status.running') }
+    return subagents === undefined ? [primary] : [primary, subagents]
+  }
+  if (subagents !== undefined) return [subagents]
+  if (node.completed) return [{ state: 'done', label: t('status.completed') }]
+  return [{ state: 'done', label: t('status.idle') }]
 }

-/** Hover-card body: full title, relative time, and interaction/running/completed/idle status. */
+/** Hover-card body: full title, relative time, and every relevant live status. */
 function SessionHoverContent({ node, now, t }: { node: SessionNode; now: number; t: RowTranslate }) {
-  const status = sessionStatus(node, t)
+  const statuses = sessionStatuses(node, t)
  return (
    <div className={css.hoverContent}>
      <div className={css.hoverTitle}>{displayTitle(node, t)}</div>
      {/* Same placeholder rule as the row's trailing cell: no timestamp
          before the first prompt. */}
      {!node.blank && <div className={css.hoverTime}>{hoverTimeLabel(node.updatedAt, now, t)}</div>}
-      <div className={css.hoverStatus}>
-        <StateDot state={status.state} />
-        <span>{status.label}</span>
-      </div>
+      {statuses.map(status => (
+        <div className={css.hoverStatus} key={status.label}>
+          <StateDot state={status.state} />
+          <span>{status.label}</span>
+        </div>
+      ))}
    </div>
  )
 }
@@ -241,7 +274,8 @@ export function SearchResultItem({ result, currentId, onOpen, t }: {
  t: RowTranslate
 }) {
  const selected = result.id === currentId
-  const status = sessionStatus(result, t)
+  const statuses = sessionStatuses(result, t)
+  const primaryStatus = statuses[0]
  return (
    <button
      type="button"
@@ -252,10 +286,12 @@ export function SearchResultItem({ result, currentId, onOpen, t }: {
    >
      <span className={css.searchResultHeading}>
        <span className={css.slot}>
-          {(status.state !== 'done' || result.completed) && (
+          {(primaryStatus.state !== 'done' || result.completed) && (
            <>
-              <StateDot state={status.state} />
-              <span className={css.visuallyHidden}>{status.label}</span>
+              <StateDot state={primaryStatus.state} />
+              {statuses.map(status => (
+                <span className={css.visuallyHidden} key={status.label}>{status.label}</span>
+              ))}
            </>
          )}
        </span>
@@ -277,7 +313,7 @@ function rowHalf(e: { clientY: number; currentTarget: HTMLElement }): 'before' |

 /**
 * One top-level 34px session row: status dot (pending user interaction outranks
- * running), title, relative time, and the row actions menu.
+ * own or descendant activity), title, relative time, and the row actions menu.
 * @param props.node - derived session node.
 * @param props.currentId - selected session id (row highlight).
 * @param props.now - epoch ms for relative-time formatting.
@@ -307,7 +343,8 @@ export function SessionNodeItem({ node, currentId, now, onOpen, onRename, onFork
  const row = node
  const title = displayTitle(node, t)
  const selected = node.id === currentId
-  const status = sessionStatus(node, t)
+  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
@@ -352,14 +389,16 @@ export function SessionNodeItem({ node, currentId, now, onOpen, onRename, onFork
          drag.drop(rowHalf(e))
        }}
    >
-      {/* Pending interactions and running outrank the idle state; a
-          finished-but-unviewed session shows the green done reminder dot
-          (cleared by opening the session). */}
+      {/* Pending interaction and own or descendant activity outrank the
+          finished-but-unviewed reminder, which returns after activity stops
+          and is cleared by opening the session. */}
      <span className={css.slot}>
-        {(status.state !== 'done' || row.completed) && (
+        {(primaryStatus.state !== 'done' || row.completed) && (
          <>
-            <StateDot state={status.state} />
-            <span className={css.visuallyHidden}>{status.label}</span>
+            <StateDot state={primaryStatus.state} />
+            {statuses.map(status => (
+              <span className={css.visuallyHidden} key={status.label}>{status.label}</span>
+            ))}
          </>
        )}
      </span>
--- a/packages/client/ui-workspace/src/client/tree.ts
+++ b/packages/client/ui-workspace/src/client/tree.ts
@@ -3,9 +3,10 @@
 * Unassigned Sessions trail under Ungrouped; only the selected blank Session
 * remains visible.
 */
-import type {
-  PendingInteractionStatus, SessionId, SessionListState, SessionSearchResultItem, SessionSummary,
-  WorkspaceId, WorkspaceView,
+import {
+  indexSubagentDescendants, type PendingInteractionStatus, type SessionId, type SessionListState,
+  type SessionSearchResultItem, type SessionSummary, type SubagentDescendantSummary,
+  type WorkspaceId, type WorkspaceView,
 } from '@deepseek-ai/dsh-client-runtime/client'

 /** Group key for Sessions outside every Workspace. */
@@ -24,6 +25,8 @@ export interface SessionNode {
  /** The runtime Session list reports an interaction awaiting this user. */
  pendingInteraction?: PendingInteractionStatus
  running: boolean
+  /** Running descendants connected through uninterrupted subagent-origin lineage. */
+  runningSubagentCount: number
  /** Finished running while not selected and not yet opened (the green "done" reminder dot). */
  completed: boolean
  updatedAt: number
@@ -56,6 +59,8 @@ export interface SearchResultNode {
  /** The runtime Session list reports an interaction awaiting this user. */
  pendingInteraction?: PendingInteractionStatus
  running: boolean
+  /** Running descendants connected through uninterrupted subagent-origin lineage. */
+  runningSubagentCount: number
  /** Finished running while not selected and not yet opened (the green "done" reminder dot). */
  completed: boolean
  snippet?: string
@@ -173,12 +178,16 @@ function groupByWorkspace(
  return groups
 }

-function sessionNode(s: SessionSummary): SessionNode {
+function sessionNode(
+  s: SessionSummary,
+  descendants: ReadonlyMap<SessionId, SubagentDescendantSummary>,
+): SessionNode {
  return {
    id: s.id,
    title: sessionTitle(s),
    blank: s.blank,
    running: s.running,
+    runningSubagentCount: descendants.get(s.id)?.runningCount ?? 0,
    completed: s.completed === true,
    updatedAt: s.updatedAt,
    ...(s.pendingInteraction === undefined ? {} : { pendingInteraction: s.pendingInteraction }),
@@ -207,6 +216,7 @@ export function deriveGroups(
 ): GroupNode[] {
  const archived = new Set(archivedSessionIds)
  const expandedProjects = new Set(view.expandedProjects)
+  const descendants = indexSubagentDescendants(list.byId)
  const currentGroup = list.current === undefined
    ? undefined
    : (workspaces.find(w => w.sessionIds.includes(list.current as SessionId))?.workspaceId as string | undefined)
@@ -223,7 +233,7 @@ export function deriveGroups(
      sessionCount: g.sessions.length,
      expanded,
      containsCurrent: g.key === currentGroup,
-      sessions: expanded ? g.sessions.map(sessionNode) : [],
+      sessions: expanded ? g.sessions.map(session => sessionNode(session, descendants)) : [],
    })
  }
  return groups
@@ -240,6 +250,7 @@ export function deriveGroups(
 */
 export function deriveFlat(list: SessionListState, archivedSessionIds: readonly SessionId[]): SessionNode[] {
  const archived = new Set(archivedSessionIds)
+  const descendants = indexSubagentDescendants(list.byId)
  const rows: SessionSummary[] = []
  for (const id of list.ids) {
    const s = list.byId[id]
@@ -247,7 +258,7 @@ export function deriveFlat(list: SessionListState, archivedSessionIds: readonly
    rows.push(s)
  }
  rows.sort(byRecency)
-  return rows.map(sessionNode)
+  return rows.map(session => sessionNode(session, descendants))
 }

 /** Relative-time bucket of a session row's trailing label. */
@@ -282,6 +293,7 @@ export function deriveSearchResults(
  const q = query.trim().toLowerCase()
  if (q === '') return { items: [], hasMore: false }
  const archived = new Set(archivedSessionIds)
+  const descendants = indexSubagentDescendants(list.byId)

  const workspaceBySession = new Map<SessionId, string>()
  for (const workspace of workspaces) {
@@ -332,6 +344,7 @@ export function deriveSearchResults(
        title: sessionTitle(summary),
        workspace: labelOf(summary),
        running: summary.running,
+        runningSubagentCount: descendants.get(summary.id)?.runningCount ?? 0,
        ...(summary.pendingInteraction === undefined
          ? {}
          : { pendingInteraction: summary.pendingInteraction }),
--- a/packages/client/ui-workspace/tests/rows.spec.tsx
+++ b/packages/client/ui-workspace/tests/rows.spec.tsx
@@ -64,6 +64,7 @@ describe('workspace browser rows', () => {
      title: 'Result title',
      workspace: 'Workspace context',
      running: true,
+      runningSubagentCount: 0,
      completed: false,
      snippet: 'matching message excerpt',
    }
@@ -86,7 +87,7 @@ describe('workspace browser rows', () => {
  ] as const)('shows %s ahead of running in search results', (pendingInteraction, label) => {
    const result: SearchResultNode = {
      id: sid(pendingInteraction), title: 'Needs input', workspace: 'Project',
-      pendingInteraction, running: true, completed: false,
+      pendingInteraction, running: true, runningSubagentCount: 0, completed: false,
    }
    render(<SearchResultItem result={result} currentId={undefined} onOpen={vi.fn()} t={t} />)
    const row = screen.getByRole('treeitem')
@@ -115,7 +116,8 @@ describe('workspace browser rows', () => {

  it('renders and opens a selected running Session row', () => {
    const node: SessionNode = {
-      id: sid('session'), title: 'Session', blank: false, running: true, completed: false, updatedAt: 0,
+      id: sid('session'), title: 'Session', blank: false, running: true,
+      runningSubagentCount: 0, completed: false, updatedAt: 0,
    }
    const onOpen = vi.fn()
    render(
@@ -131,10 +133,13 @@ describe('workspace browser rows', () => {
    expect(onOpen).toHaveBeenCalledWith(node.id)
  })

-  it('shows the green done dot only on a finished, unviewed session (running wins the slot)', () => {
+  it('shows the green done dot only on a finished, unviewed session (live activity wins the slot)', () => {
    const renderRow = (over: Partial<SessionNode>) => render(
      <SessionNodeItem
-        node={{ id: sid('s1'), title: 'One', blank: false, running: false, completed: false, updatedAt: 0, ...over }}
+        node={{
+          id: sid('s1'), title: 'One', blank: false, running: false,
+          runningSubagentCount: 0, completed: false, updatedAt: 0, ...over,
+        }}
        currentId={undefined} now={0} onOpen={vi.fn()}
        onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t}
      />,
@@ -153,11 +158,78 @@ describe('workspace browser rows', () => {
    const running = renderRow({ completed: true, running: true })
    expect(running.container.querySelector('[data-state="ongoing"]')).not.toBeNull()
    expect(running.container.querySelector('[data-state="done"]')).toBeNull()
+    running.unmount()
+    // Descendant activity also wins until the last running descendant stops.
+    const delegated = renderRow({ completed: true, runningSubagentCount: 1 })
+    expect(delegated.container.querySelector('[data-state="ongoing"]')).not.toBeNull()
+    expect(delegated.container.querySelector('[data-state="done"]')).toBeNull()
+  })
+
+  it('shows descendant activity without describing an idle parent as running', () => {
+    vi.useFakeTimers()
+    try {
+      const node: SessionNode = {
+        id: sid('owner'), title: 'Delegating', blank: false, running: false,
+        runningSubagentCount: 2, completed: false, updatedAt: 0,
+      }
+      render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
+        onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
+      const row = screen.getByRole('treeitem')
+      expect(row.querySelector('[data-state="ongoing"]')).not.toBeNull()
+      expect(screen.getByText('2 个子代理运行中')).toBeTruthy()
+      expect(screen.queryByText('进行中')).toBeNull()
+
+      fireEvent.pointerEnter(row.parentElement as HTMLElement)
+      act(() => { vi.advanceTimersByTime(500) })
+      expect(screen.getAllByText('2 个子代理运行中')).toHaveLength(2)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('keeps descendant activity secondary while the parent is running', () => {
+    vi.useFakeTimers()
+    try {
+      const node: SessionNode = {
+        id: sid('owner'), title: 'Delegating', blank: false, running: true,
+        runningSubagentCount: 1, completed: false, updatedAt: 0,
+      }
+      render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
+        onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
+      const row = screen.getByRole('treeitem')
+      expect(row.querySelectorAll('[data-state="ongoing"]')).toHaveLength(1)
+      expect(screen.getByText('进行中')).toBeTruthy()
+      expect(screen.getByText('1 个子代理运行中')).toBeTruthy()
+
+      fireEvent.pointerEnter(row.parentElement as HTMLElement)
+      act(() => { vi.advanceTimersByTime(500) })
+      expect(screen.getAllByText('进行中')).toHaveLength(2)
+      expect(screen.getAllByText('1 个子代理运行中')).toHaveLength(2)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('keeps child activity as a secondary status while user attention is primary', () => {
+    const node: SessionNode = {
+      id: sid('owner'), title: 'Needs input', blank: false, pendingInteraction: 'question',
+      running: false, runningSubagentCount: 1, completed: false, updatedAt: 0,
+    }
+    render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
+      onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
+    const row = screen.getByRole('treeitem')
+    expect(row.querySelector('[data-state="warning"]')).not.toBeNull()
+    expect(row.querySelector('[data-state="ongoing"]')).toBeNull()
+    expect(screen.getByText('等待回答')).toBeTruthy()
+    expect(screen.getByText('1 个子代理运行中')).toBeTruthy()
  })

  it('shows the green done dot on a finished search result row', () => {
    render(<SearchResultItem
-      result={{ id: sid('result'), title: 'Done', workspace: 'Workspace', running: false, completed: true }}
+      result={{
+        id: sid('result'), title: 'Done', workspace: 'Workspace', running: false,
+        runningSubagentCount: 0, completed: true,
+      }}
      currentId={undefined} onOpen={vi.fn()} t={t}
    />)
    expect(screen.getByRole('treeitem').querySelector('[data-state="done"]')).not.toBeNull()
@@ -231,7 +303,8 @@ describe('workspace browser rows', () => {
    vi.useFakeTimers()
    try {
      const node: SessionNode = {
-        id: sid('s-blank'), title: 'ignored', blank: true, running: false, completed: false, updatedAt: 0,
+        id: sid('s-blank'), title: 'ignored', blank: true, running: false,
+        runningSubagentCount: 0, completed: false, updatedAt: 0,
      }
      render(<SessionNodeItem node={node} currentId={node.id} now={0} onOpen={vi.fn()}
        onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
@@ -257,7 +330,8 @@ describe('workspace browser rows', () => {
    const onFork = vi.fn()
    const onArchive = vi.fn()
    const node: SessionNode = {
-      id: sid('s1'), title: 'One', blank: false, running: false, completed: false, updatedAt: 0,
+      id: sid('s1'), title: 'One', blank: false, running: false,
+      runningSubagentCount: 0, completed: false, updatedAt: 0,
    }
    render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={onOpen}
      onRename={onRename} onFork={onFork} onArchive={onArchive} t={t} />)
@@ -290,7 +364,8 @@ describe('workspace browser rows', () => {
    vi.useFakeTimers()
    try {
      const node: SessionNode = {
-        id: sid('s1'), title: 'Hovered', blank: false, running: true, completed: false, updatedAt: 0,
+        id: sid('s1'), title: 'Hovered', blank: false, running: true,
+        runningSubagentCount: 0, completed: false, updatedAt: 0,
      }
      render(<SessionNodeItem node={node} currentId={undefined} now={60_000} onOpen={vi.fn()}
        onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
@@ -321,7 +396,7 @@ describe('workspace browser rows', () => {
    try {
      const node: SessionNode = {
        id: sid(pendingInteraction), title: 'Needs input', blank: false,
-        pendingInteraction, running: true, completed: false, updatedAt: 0,
+        pendingInteraction, running: true, runningSubagentCount: 0, completed: false, updatedAt: 0,
      }
      const view = render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
        onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
@@ -347,7 +422,8 @@ describe('workspace browser rows', () => {
    vi.useFakeTimers()
    try {
      const node: SessionNode = {
-        id: sid('s1'), title: 'Quiet', blank: false, running: false, completed: false, updatedAt: 0,
+        id: sid('s1'), title: 'Quiet', blank: false, running: false,
+        runningSubagentCount: 0, completed: false, updatedAt: 0,
      }
      render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
        onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
@@ -364,7 +440,8 @@ describe('workspace browser rows', () => {
    vi.useFakeTimers()
    try {
      const node: SessionNode = {
-        id: sid('s1'), title: 'Done', blank: false, running: false, completed: true, updatedAt: 0,
+        id: sid('s1'), title: 'Done', blank: false, running: false,
+        runningSubagentCount: 0, completed: true, updatedAt: 0,
      }
      render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
        onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
@@ -379,7 +456,8 @@ describe('workspace browser rows', () => {

  it('draggable row wires start/end and gates hover/drop on an active same-group drag', () => {
    const node: SessionNode = {
-      id: sid('s1'), title: 'Drag me', blank: false, running: false, completed: false, updatedAt: 0,
+      id: sid('s1'), title: 'Drag me', blank: false, running: false,
+      runningSubagentCount: 0, completed: false, updatedAt: 0,
    }
    const inactive = dragProps()
    const { rerender } = render(
--- a/packages/client/ui-workspace/tests/tree.spec.ts
+++ b/packages/client/ui-workspace/tests/tree.spec.ts
@@ -95,18 +95,35 @@ describe('deriveGroups', () => {

  it('hides subagent-origin sessions without hiding ordinary forks', () => {
    const parent = summary('parent', 1)
-    const fork = { ...summary('fork', 2), parentId: parent.id }
-    const subagent = { ...summary('subagent', 3), parentId: parent.id, origin: 'subagent' as const }
-    const sessions = { ...list(parent, fork, subagent), current: subagent.id }
+    const subagent = {
+      ...summary('subagent', 3), parentId: parent.id, origin: 'subagent' as const, running: true,
+    }
+    const grandchild = {
+      ...summary('grandchild', 4), parentId: subagent.id, origin: 'subagent' as const, running: true,
+    }
+    const fork = { ...summary('fork', 2), parentId: subagent.id }
+    const forkChild = {
+      ...summary('fork-child', 5), parentId: fork.id, origin: 'subagent' as const, running: true,
+    }
+    const sessions = { ...list(parent, fork, subagent, grandchild, forkChild), current: subagent.id }
    const groups = deriveGroups(
      sessions,
-      [workspace('first', ['parent', 'fork', 'subagent'])],
+      [workspace('first', ['parent', 'fork', 'subagent', 'grandchild', 'fork-child'])],
      noArchive,
      view(['first']),
    )

    expect(groups[0]!.sessions.map(node => node.id)).toEqual([parent.id, fork.id])
    expect(groups[0]!.sessionCount).toBe(2)
+    expect(groups[0]!.sessions[0]).toMatchObject({ running: false, runningSubagentCount: 2 })
+    expect(groups[0]!.sessions[1]).toMatchObject({ running: false, runningSubagentCount: 1 })
+    expect(deriveFlat(sessions, noArchive).map(node => [node.id, node.runningSubagentCount])).toEqual([
+      [fork.id, 1], [parent.id, 2],
+    ])
+    expect(deriveSearchResults(
+      sessions, [workspace('first', ['parent', 'fork'])], 'parent', noArchive,
+      { items: [], hasMore: false }, 10,
+    ).items[0]).toMatchObject({ id: parent.id, runningSubagentCount: 2 })
  })

  it('ignores fork lineage and sorts every ungrouped session as a top-level row', () => {
@@ -274,6 +291,7 @@ describe('deriveSearchResults', () => {
          title: 'Needle title',
          workspace: 'Alpha',
          running: false,
+          runningSubagentCount: 0,
          pendingInteraction: 'plan-review',
          completed: false,
          snippet: 'title session body excerpt',
@@ -283,6 +301,7 @@ describe('deriveSearchResults', () => {
          title: 'Ordinary title',
          workspace: 'Needle Workspace',
          running: false,
+          runningSubagentCount: 0,
          completed: false,
        },
        {
@@ -290,6 +309,7 @@ describe('deriveSearchResults', () => {
          title: 'content-hit',
          workspace: 'c',
          running: false,
+          runningSubagentCount: 0,
          completed: false,
          snippet: 'body needle excerpt',
        },
--- a/packages/client/web-react/tsdown.config.ts
+++ b/packages/client/web-react/tsdown.config.ts
@@ -1,4 +1,4 @@
-import { defineConfig } from 'tsdown'
+import { clientOnly } from '../tsdown.client.ts'

 /**
 * Root and invariant shapes as SEPARATE single-entry bundles: a multi-entry
@@ -8,7 +8,7 @@ import { defineConfig } from 'tsdown'
 * runtime — browser consumers resolve this package through the loader module
 * table.
 */
-export default defineConfig([
+export default clientOnly([
  {
    entry: { index: 'lib/types/index.js' },
    outDir: 'lib',
--- a/packages/client/web/tsdown.config.ts
+++ b/packages/client/web/tsdown.config.ts
@@ -1,4 +1,4 @@
-import { defineConfig } from 'tsdown'
+import { clientOnly } from '../tsdown.client.ts'

 /**
 * Root-shape lib build plus a css stub: the shell's components import
@@ -8,7 +8,7 @@ import { defineConfig } from 'tsdown'
 * this node lib build stubs every css import to an empty module — importing
 * the lib under plain node must not crash on an asset specifier.
 */
-export default defineConfig({
+export default clientOnly([{
  entry: ['lib/types/index.js', 'lib/types/invariant.js'],
  outDir: 'lib',
  format: ['esm'],
@@ -28,4 +28,4 @@ export default defineConfig({
      return 'export default {};'
    },
  }],
-})
+}])
--- 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: a32a6aeb9957f0fd5f8cff58b1edbb9bc29a4e3d
-README.zh.md: c678f522115d9b0fd414b2f290b3cb54ce690722
+README.md: 54f341e39447a423964b7d7435cfb638857eda6e
+README.zh.md: d4a122b8a19cdf907212ad019b2528ae52d03886
--- a/packages/compact/command-compact/README.md
+++ b/packages/compact/command-compact/README.md
@@ -12,7 +12,7 @@ Human-facing `/compact` control over [`ctx.compact`](../compact/README.md). The
 | `/compact` with no compactable history | `No compactable history yet.` — no marker or surface mutation is written. |
 | `/compact <anything>` | `Usage: /compact (no arguments)` — the command takes no arguments and calls no compaction backend. |

-The command is backend-independent: it depends only on `compactNow(agent, signal)`. The invoking agent is the exact target, and the dispatching UI's cancellation signal is forwarded through the seam. Every resolved invocation records the executor-owned log-only pair `command/run` / `command/done`; neither event joins model history.
+The command is backend-independent: it depends only on `compactNow(agent, signal)`. The invoking agent is the exact target, and the dispatching UI's cancellation signal is forwarded through the seam. Every resolved invocation records the executor-owned log-only pair `command/run` / `command/done`; neither event joins model history. On success, `command/done.sourceEventSeq` names the transaction's `compact/summary` event so a presentation can fold the command lifecycle into its checkpoint without parsing result text or assuming adjacent rows.

 Expected `ManualCompactionError` codes become stable direct errors:

--- a/packages/compact/command-compact/README.zh.md
+++ b/packages/compact/command-compact/README.zh.md
@@ -12,7 +12,7 @@
 | `/compact`，但没有可压缩历史 | `No compactable history yet.`：不会写入标记，也不会变更 surface。 |
 | `/compact <anything>` | `Usage: /compact (no arguments)`：该命令不接受参数，也不会调用压缩后端。 |

-该命令与后端无关，只依赖 `compactNow(agent, signal)`。调用该命令的 agent（智能体）就是操作的确切目标，发起分发的 UI 会通过 seam 转发取消信号。每次完成的调用都会记录执行器所属的纯日志事件对 `command/run` / `command/done`；两者都不进入模型历史。
+该命令与后端无关，只依赖 `compactNow(agent, signal)`。调用该命令的 agent（智能体）就是操作的确切目标，发起分发的 UI 会通过 seam 转发取消信号。每次完成的调用都会记录执行器所属的纯日志事件对 `command/run` / `command/done`；两者都不进入模型历史。成功时，`command/done.sourceEventSeq` 会指明该事务的 `compact/summary` 事件，让呈现层无须解析结果文本或假定两行相邻，即可将命令生命周期归并到对应检查点中。

 预期的 `ManualCompactionError` 代码会成为稳定的直接错误：

--- a/packages/compact/command-compact/src/index.ts
+++ b/packages/compact/command-compact/src/index.ts
@@ -68,6 +68,7 @@ async function executeCompact(
    return {
      kind: 'success',
      text: `Compacted ${result.shadowedSeqs.length} history items (~${result.shadowedTokenCount} tokens).`,
+      sourceEventSeq: result.summarySeq,
    }
  } catch (error: unknown) {
    if (invocation.signal.aborted) return { kind: 'error', text: 'Compaction cancelled.' }
--- a/packages/compact/command-compact/tests/command-compact.spec.ts
+++ b/packages/compact/command-compact/tests/command-compact.spec.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import CommandService from '@deepseek-ai/dsh-commands'
+import CommandService, { type CommandResult } from '@deepseek-ai/dsh-commands'
 import {
  CompactService,
  ManualCompactionError,
@@ -15,9 +15,9 @@ import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import * as commandCompact from '@deepseek-ai/dsh-command-compact'

 const RESULT: CompactionResult = {
-  startSeq: 10,
-  summarySeq: 11,
-  endSeq: 13,
+  startSeq: 1,
+  summarySeq: 2,
+  endSeq: 3,
  summary: [{ type: 'text', text: 'summary' }],
  shadowedRange: { start: 1, end: 7 },
  shadowedSeqs: [1, 3, 7],
@@ -49,10 +49,24 @@ class StubCompactService extends CompactService {
    this.calls.push({ agent, signal })
    if (this.operation !== undefined) return this.operation()
    return this.failure === undefined
-      ? Promise.resolve(this.result)
+      ? Promise.resolve(this.result === null ? null : this.appendResult(agent, this.result))
      // 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 })
+    agent.session.append('compact/summary', {
+      summary: result.summary,
+      shadowedRange: result.shadowedRange,
+      shadowedSeqs: result.shadowedSeqs,
+      shadowedTokenCount: result.shadowedTokenCount,
+      provider: 'command-test',
+      model: 'command-test',
+    })
+    agent.session.append('compact/end', { turn: null })
+    return result
+  }
 }

 interface Harness {
@@ -91,9 +105,11 @@ async function run(
 function expectLastLifecycle(
  test: Harness,
  args: string,
-  outcome: { readonly kind: 'success' | 'error'; readonly text?: string },
+  outcome: CommandResult,
 ): string {
-  const lifecycle = test.agent.session.events.slice(-2)
+  const lifecycle = test.agent.session.events
+    .filter(event => event.type === 'command/run' || event.type === 'command/done')
+    .slice(-2)
  const runEvent = lifecycle[0]
  const doneEvent = lifecycle[1]
  if (runEvent?.type !== 'command/run' || doneEvent?.type !== 'command/done') {
@@ -149,6 +165,7 @@ describe('/compact human command', () => {
    expect(execution.result).toEqual({
      kind: 'success',
      text: 'Compacted 3 history items (~42 tokens).',
+      sourceEventSeq: RESULT.summarySeq,
    })
    expect(execution.commandId).toBe(expectLastLifecycle(test, '', execution.result))
    expect(test.compact.calls).toEqual([{ agent: test.agent, signal: controller.signal }])
--- a/packages/compact/command-compact/tests/loader-composition.spec.ts
+++ b/packages/compact/command-compact/tests/loader-composition.spec.ts
@@ -21,7 +21,7 @@ import { Session, SessionId } from '@deepseek-ai/dsh-session'
 const RESULT: CompactionResult = {
  startSeq: 1,
  summarySeq: 2,
-  endSeq: 4,
+  endSeq: 3,
  summary: [{ type: 'text', text: 'loader summary' }],
  shadowedRange: { start: 3, end: 8 },
  shadowedSeqs: [3, 5, 8],
@@ -42,9 +42,19 @@ class LoaderCompactService extends CompactService {
  }

  override compactNow(
-    _agent: ManualCompactAgentContext,
+    agent: ManualCompactAgentContext,
    _signal: AbortSignal,
  ): Promise<CompactionResult | null> {
+    agent.session.append('compact/start', { turn: null })
+    agent.session.append('compact/summary', {
+      summary: RESULT.summary,
+      shadowedRange: RESULT.shadowedRange,
+      shadowedSeqs: RESULT.shadowedSeqs,
+      shadowedTokenCount: RESULT.shadowedTokenCount,
+      provider: 'loader-test',
+      model: 'loader-test',
+    })
+    agent.session.append('compact/end', { turn: null })
    return Promise.resolve(RESULT)
  }
 }
@@ -108,6 +118,7 @@ describe('command-compact real Loader composition', () => {
    expect(execution.result).toEqual({
      kind: 'success',
      text: 'Compacted 3 history items (~99 tokens).',
+      sourceEventSeq: RESULT.summarySeq,
    })
    expect(session.events.map(event => ({ type: event.type, data: event.data }))).toEqual([
      {
@@ -119,12 +130,32 @@ describe('command-compact real Loader composition', () => {
          source: { kind: 'user' },
        },
      },
+      {
+        type: 'compact/start',
+        data: { turn: null },
+      },
+      {
+        type: 'compact/summary',
+        data: {
+          summary: RESULT.summary,
+          shadowedRange: RESULT.shadowedRange,
+          shadowedSeqs: RESULT.shadowedSeqs,
+          shadowedTokenCount: RESULT.shadowedTokenCount,
+          provider: 'loader-test',
+          model: 'loader-test',
+        },
+      },
+      {
+        type: 'compact/end',
+        data: { turn: null },
+      },
      {
        type: 'command/done',
        data: {
          commandId: execution.commandId,
          kind: 'success',
          text: 'Compacted 3 history items (~99 tokens).',
+          sourceEventSeq: RESULT.summarySeq,
        },
      },
    ])
--- 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: 0c7b009255dc2d41dc81cf2c7ff745e02ef28b9a
-README.zh.md: 4af584a059c99725882afd6206bdf9c984c7d4e3
+README.md: 4241899788998a744801bb0406a15ecd70af6401
+README.zh.md: c1df4afaa1837a3b689da80cc1b49df43f60e513
--- a/packages/compact/compact-basic/README.md
+++ b/packages/compact/compact-basic/README.md
@@ -21,7 +21,7 @@ This backend owns the compaction policy:
 - **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?, provider, model, maxTokens?, usage? }`); 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, 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`.

 ## Config (`BasicCompactConfig`)

--- a/packages/compact/compact-basic/README.zh.md
+++ b/packages/compact/compact-basic/README.zh.md
@@ -21,7 +21,7 @@
 - **溢出恢复**：提供方已确认的溢出不需容量元数据。它会绕过常规压力与保留，执行剪枝，再尝试一次最大平衡头部缩减，并留下最新不可分单元。只要 `surface.replaceGeneration` 前进，就允许重试，包括剪枝在后续摘要工作抛出异常前已落地的情况。如果没有替换、目标特定上限已耗尽、已取消，或遇到未知／非规范错误，则保留原始提供方失败。
 - **失败处理**：活动的未匹配 `compact/start` 是持久锁。位于较新 `session/end-seed` 之前的未匹配标记，是先前生命周期留下的陈旧证据，不会阻塞；位于该边界之后的标记报告 `busy`。摘要和 span 变更失败会以错误闭合，并保持会话表层不变，但日志中仍保留该尝试。闭合失败会有意留下阻塞性的未匹配标记。压力检查中的运行故障会发出警告并继续；只有此前没有替换推进表层时，溢出恢复失败才保留原始提供方错误。完成清理与持久化后，取消仍具有最终决定权。

-受保护的 `summarize()` 方法是唯一的子类钩子。基于模板或远程摘要器的子类可以覆盖该方法，同时压力、保留、溯源、缩减验证与已遮蔽 token 计量仍由 `ctx.tokenMeter` 负责。钩子返回安全摘要，以及完整提供方输出、调用 envelope 和可用时的 usage（`{ summary, rawOutput?, provider, model, maxTokens?, usage? }`）；事务会在 `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`）

--- a/packages/compact/compact-basic/src/region.ts
+++ b/packages/compact/compact-basic/src/region.ts
@@ -43,7 +43,7 @@ interface PreparedCompaction extends SurfaceSelection {
  readonly input: SummarizationInput
 }

-interface SummarizedCompaction extends PreparedCompaction, SummaryResult {
+type SummarizedCompaction = PreparedCompaction & SummaryResult & {
  readonly checkpointMessage: UserMessage
 }

@@ -415,16 +415,18 @@ function commitCompactionBody(
    shadowedSeqs,
    shadowedTokenCount,
    summary,
-    rawOutput,
    provider,
    model,
    maxTokens,
    usage,
    checkpointMessage,
  } = summarized
+  const callProvenance = summarized.llmStreamCall === true
+    ? { rawOutput: summarized.rawOutput, llmStreamCall: true as const }
+    : summarized.rawOutput === undefined ? {} : { rawOutput: summarized.rawOutput }
  const summaryEvent = session.append('compact/summary', {
    summary,
-    ...rawOutput === undefined ? {} : { rawOutput },
+    ...callProvenance,
    shadowedRange: { start, end },
    shadowedSeqs: [...shadowedSeqs],
    shadowedTokenCount,
--- a/packages/compact/compact-basic/src/summarizer.ts
+++ b/packages/compact/compact-basic/src/summarizer.ts
@@ -85,16 +85,27 @@ export interface SummarizationInput {
 }

 /** Safe summary content plus the exact auxiliary call envelope recorded in provenance. */
-export interface SummaryResult {
+export type SummaryResult = {
  summary: ContentBlock[]
-  /** Complete provider output before the text-only summary projection. */
-  rawOutput?: ContentBlock[]
  provider: string
  model: string
  maxTokens?: number
  /** Provider-reported usage for this summarization request. */
  usage?: TokenUsage
-}
+} & (
+  | {
+    /** Complete provider output before the text-only 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 result does not identify a call through this context's LLM seam. */
+    llmStreamCall?: never
+  }
+)

 /**
 * Run the default cache-reusing `ctx.llm.stream()` summarization call: replay
@@ -162,6 +173,7 @@ export async function summarizeWithLlm(
  return {
    summary,
    rawOutput,
+    llmStreamCall: true,
    provider: options.provider,
    model: options.model,
    maxTokens: config.maxTokens,
--- a/Show More
+++ b/Show More