chore(gen1): 第一代版本封板 — DSH 2.0.17 兼容 + settings API 迁移 + React #130 修复

- peerDeps 升级到 0.2.0-rc.2
- settings API 迁移: register() → describe() + settings/document-updated
- turnTail slots.register 补 id 字段
- EditorHost viewer.component undefined guard
- 56/56 测试全绿, typecheck/build 通过

tag: v1.2.0-gen1

.github/ISSUE_TEMPLATE/issue_report.yml

@@ -16,7 +16,7 @@ body:
       options:
         - label: 我已搜索现有 issue，确认没有**完全相同**的条目（只有完全一致才算重复）| I searched existing issues and confirmed there is no **exact duplicate** (only exactly identical issues count as duplicates)
           required: true
-        - label: 我已确认使用最新版本 dsh-better-sidebar / I confirmed I am on the latest dsh-better-sidebar version
+        - label: 我已确认使用最新版本 dsh-apes-sidebar / I confirmed I am on the latest dsh-apes-sidebar version
           required: false
 
   - type: dropdown
@@ -58,8 +58,8 @@ body:
     id: plugin-version
     attributes:
       label: 插件版本 / Plugin version
-      description: dsh-better-sidebar 的版本号 | The dsh-better-sidebar version
-      placeholder: "如 0.13.1（`dsh plugin --profile web add dsh-better-sidebar@latest` 安装的版本）"
+      description: dsh-apes-sidebar 的版本号 | The dsh-apes-sidebar version
+      placeholder: "如 0.13.1（`dsh plugin --profile web add dsh-apes-sidebar@latest` 安装的版本）"
     validations:
       required: false
 

.github/workflows/ci.yml

@@ -35,7 +35,7 @@ jobs:
       # config; the runner has none by default.
       - name: Configure git identity for tests
         run: |
-          git config --global user.name "dsh-better-sidebar-ci"
+          git config --global user.name "dsh-apes-sidebar-ci"
           git config --global user.email "ci@dsh.invalid"
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
@@ -84,7 +84,7 @@ jobs:
       # identity and rely on ambient config, which the runner lacks.
       - name: Configure git identity for tests
         run: |
-          git config --global user.name "dsh-better-sidebar-ci"
+          git config --global user.name "dsh-apes-sidebar-ci"
           git config --global user.email "ci@dsh.invalid"
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
@@ -92,8 +92,28 @@ jobs:
         run: pnpm typecheck
       - name: Lint
         run: pnpm lint
+      # `test:windows` runs the whole suite in ONE fork (`--maxWorkers=1`),
+      # not `pnpm test`'s unbounded pool. Two distinct Windows-only failures
+      # motivated it, both recorded in docs/plans/2026-09-10-dsh-0.1.5-rc.2-adaptation.md:
+      #
+      #   1. Six red runs were real 5000 ms vitest timeouts in specs that
+      #      really start a process (tests/agent-pty:71/:106,
+      #      tests/install-powershell:105 — a cold powershell.exe start
+      #      measured 12.1 s, tests/git.spec.ts:85 at 9.6 s). The suite now
+      #      declares its own budgets (global testTimeout 15 s, 30 s in the
+      #      two heaviest describes), and serial execution stops the
+      #      process-spawning specs starving each other on a 2-core runner.
+      #   2. Four runs died at teardown with `[vitest-pool]: Worker forks
+      #      emitted error / Worker exited unexpectedly` while reporting
+      #      N-1 of N files passed and zero FAIL lines — a worker recycling
+      #      race, not a test failure. It survived --maxWorkers=2, so the
+      #      lane now recycles nothing at all.
+      #
+      # No retries: they would hide a real regression instead of removing the
+      # race. The cost is wall-clock (the Windows step runs several minutes
+      # against a 30-minute job budget), not signal.
       - name: Test
-        run: pnpm test
+        run: pnpm test:windows
       - name: Build
         run: pnpm build
       - name: Check consumer type surface
@@ -131,10 +151,31 @@ jobs:
       # Pin the DSH CLI the lane mounts into; the profile's bundle stack
       # (dsh-base / dsh-web-app) resolves from this installation. Keep in
       # step with the plugin's @deepseek-ai/* peer range when bumping.
-      # DSH 0.1.5-alpha.2 is published under the `alpha` dist-tag; the lanes
-      # speak the slash-only RPC dialect (tests/e2e/host-protocol.ts).
+      # DSH 0.1.5-rc.2 is the `next` dist-tag on npm (`latest` still points
+      # at rc.1); the lanes speak the slash-only RPC dialect
+      # (tests/e2e/host-protocol.ts).
+      #
+      # The larger heap is the fix for one of the two ways this step used to
+      # die (runs 34490912649 and 34363627184 on the alpha line): the pinned
+      # version's TRANSITIVES are declared as floating `^` ranges, so while
+      # upstream publishes a prerelease in stages (0.1.5-rc.2 went out
+      # 14:43-14:57 on 2026-09-10) npm resolved a mixed rc.1/rc.2 peer graph —
+      # 3062 ERESOLVE lines, then "Ineffective mark-compacts near heap limit"
+      # (exit 134). The other failure mode was a hard ETARGET on a sibling
+      # package that appeared minutes later; pinning a version that is fully
+      # published (not mid-flight) is the fix for that one.
+      #
+      # Peer resolution stays ON: `--legacy-peer-deps` was tried in the first
+      # cut of this fix and made the install broken rather than robust — it
+      # skips exactly the peers a global install has to supply, and
+      # @deepseek-ai/dsh-app-boot requires `@deepseek-ai/cordis-plugin-group`
+      # (a peer, not a dependency) at boot, so the CLI died with
+      # ERR_MODULE_NOT_FOUND before the smoke could even start. Verified
+      # locally that the plain install resolves it.
       - name: Install dsh CLI (pinned)
-        run: npm install -g @deepseek-ai/dsh@0.1.5-alpha.2
+        env:
+          NODE_OPTIONS: --max-old-space-size=4096
+        run: npm install -g @deepseek-ai/dsh@0.1.5-rc.2
 
       # lib/ is gitignored; the tarball is produced from this build.
       - name: Build and pack the npm tarball
@@ -147,7 +188,7 @@ jobs:
         run: pnpm test:mount
 
       # Aggregate double-mount regression: a fixture aggregate bundle mounts
-      # dsh-better-sidebar under its own entry id BEFORE the plugin's bundle
+      # dsh-apes-sidebar under its own entry id BEFORE the plugin's bundle
       # row; the plugin must back off (no duplicate /sidebar/api, boot OK).
       # Uses the pinned DSH CLI installed above.
       - name: Aggregate double-mount regression

.github/workflows/release.yml

@@ -1,6 +1,6 @@
 name: Release
 
-# Publishes `dsh-better-sidebar` to npm via npm Trusted Publishing (OIDC) —
+# Publishes `dsh-apes-sidebar` to npm via npm Trusted Publishing (OIDC) —
 # no NPM_TOKEN secret required, provenance is attached to the tarball.
 #
 # Trigger: a GitHub Release is published (tag vX.Y.Z). The tag MUST match
@@ -12,7 +12,7 @@ name: Release
 # supports the stable DSH line); stable versions publish as `latest`.
 #
 # One-time npm-side setup (manual, on npmjs.com):
-#   1. package `dsh-better-sidebar` -> Settings -> Publishing access
+#   1. package `dsh-apes-sidebar` -> Settings -> Publishing access
 #      -> Trusted Publishers -> "Add Trusted Publisher".
 #   2. Provider: GitHub Actions
 #      Organization or user: omdsh-dev
@@ -66,7 +66,7 @@ jobs:
       # (see tests/smoke.spec.ts); the runner has none by default.
       - name: Configure git identity for tests
         run: |
-          git config --global user.name "dsh-better-sidebar-ci"
+          git config --global user.name "dsh-apes-sidebar-ci"
           git config --global user.email "ci@dsh.invalid"
 
       - name: Install dependencies

AGENTS.md

@@ -1,4 +1,4 @@
-# dsh-better-sidebar 仓库规则（AGENTS）
+# dsh-apes-sidebar 仓库规则（AGENTS）
 
 > 本文只含**项目全局开发规则**（面向贡献者与 agent）。
 > 消费插件接入 API 全参考（`ctx.betterSidebar` 服务、TabDescriptor / FileViewerDescriptor 全字段、声明式设置、原生右侧栏承载面、皮肤契约等）→ [docs/external-plugin-guide.md](docs/external-plugin-guide.md)；逐特性设计史（含实施偏差记录）→ [docs/plans/](docs/plans/)。
@@ -17,15 +17,15 @@
 
 ## 2. CI 挂载冒烟（`plugin-mount` job / `pnpm test:mount`）
 
-「npm 打包 → 真实挂载 → 无头渲染」门禁（证明打包产物在真实 DSH 挂载后不 crash）：`pnpm build && pnpm pack` 产 tarball → `scripts/e2e-mount.sh` 装进全新 scratch profile（`dsh plugin --profile web add <tarball>`）并启动真实 `dsh web`（keyless，`--port 0`）→ `tests/e2e/mount.e2e.ts`（Playwright）断言 `[data-dsh-better-sidebar]` 挂载、无错误条/pageerror/console 错误，展开 DSH 原生右侧栏后经其 guide 页逐个打开插件 tab 类型（含终端懒加载 chunk），再经插件文件树（原生 `files` kind 接管）打开 seed 文件强制加载 editor chunk（`client-editor.js`），并跑 mermaid / README 预览与 sidechat 宿主路由烟测。
+「npm 打包 → 真实挂载 → 无头渲染」门禁（证明打包产物在真实 DSH 挂载后不 crash）：`pnpm build && pnpm pack` 产 tarball → `scripts/e2e-mount.sh` 装进全新 scratch profile（`dsh plugin --profile web add <tarball>`）并启动真实 `dsh web`（keyless，`--port 0`）→ `tests/e2e/mount.e2e.ts`（Playwright）断言 `[data-dsh-apes-sidebar]` 挂载、无错误条/pageerror/console 错误，展开 DSH 原生右侧栏后经其 guide 页逐个打开插件 tab 类型（含终端懒加载 chunk），再经插件文件树（原生 `files` kind 接管）打开 seed 文件强制加载 editor chunk（`client-editor.js`），并跑 mermaid / README 预览与 sidechat 宿主路由烟测。
 
-本地：`pnpm build && pnpm pack && pnpm exec playwright install chromium && pnpm test:mount`。CI 钉 `@deepseek-ai/dsh@0.1.5-alpha.2`（`alpha` dist-tag；peer 下限 `^0.1.5-alpha.2`）。e2e spec 命名 `*.e2e.ts` + vitest `exclude` 双保险；**改 `exclude` 必须保留默认排除项**（exclude 整体替换默认值）。
+本地：`pnpm build && pnpm pack && pnpm exec playwright install chromium && pnpm test:mount`。CI 钉 `@deepseek-ai/dsh@0.1.5-rc.2`（npm `next`；`latest` 仍是 rc.1；peer 下限 `^0.1.5-rc.1`）。该步骤用 `NODE_OPTIONS=--max-old-space-size=4096`：钉版自身的传递依赖是浮动 `^` 范围，上游分阶段发布预发布版时（rc.2 于 2026-09-10 的 14:43–14:57 逐包上线）npm 会组出混合 peer 图，3062 条 ERESOLVE 后 OOM（exit 134）；另一个失败模式是对未发布兄弟包 ETARGET，靠「钉一个已完整发布的版本」修掉。**不要加 `--legacy-peer-deps`**：它跳过的正是全局安装必须提供的 peer，`@deepseek-ai/dsh-app-boot` 在 boot 时 require 的 `@deepseek-ai/cordis-plugin-group` 是 peer 而非 dependency，加了它 CLI 直接 `ERR_MODULE_NOT_FOUND`（实测过一次，见 rc.2 计划 C 节）。`ci-windows` 的 `Test` 跑 `pnpm test:windows`（`--maxWorkers=2`）而非 `pnpm test`——多个 spec 真起进程（`agent-pty` / `pty-deps` / `pty-helpers` / `install-powershell` / `smoke`），2 核 runner 上并行起 ConPTY / 冷启 `powershell.exe` 是超时与 worker 静默死亡的放大器；`vitest.config.ts` 的全局 `testTimeout: 15_000`（默认 5000 在 Windows 上对真起进程的用例太低，三个不同文件先后翻车）是配套的一半。e2e spec 命名 `*.e2e.ts` + vitest `exclude` 双保险；**改 `exclude` 必须保留默认排除项**（exclude 整体替换默认值）。
 
 ---
 
-## 3. DSH 0.1.5 适配要点（0.1.5-alpha.2+ 基线）
+## 3. DSH 0.1.5 适配要点（0.1.5-rc.1+ 基线）
 
-**v0.19.0-alpha.1 起仅支持 DSH 0.1.5-alpha.2+**（peer 下限 `^0.1.5-alpha.2`，CI 钉 `@deepseek-ai/dsh@0.1.5-alpha.2`，DSH alpha 线发在 `alpha` dist-tag）。alpha.1 用户停留在 v0.19.0-alpha.0——alpha.2 删除了指南条目的 `description` 字段并改了文件地址语法，插件不再对 alpha.1 做运行时兼容。0.1.2-rc.1 稳定线用户继续用 v0.18.x（npm `latest`）——0.1.5 的会话事件模型与文件打开漏斗都变了，插件不再对 0.1.2 做运行时兼容。发版：release.yml 按版本号是否含 `-` 自动选 `alpha`/`latest` dist-tag。
+**v0.19.0（正式版，npm `latest`）起仅支持 DSH 0.1.5-rc.1+**（peer 下限 `^0.1.5-rc.1`，CI 钉 `@deepseek-ai/dsh@0.1.5-rc.2`）。**v0.19.1 把钉版推进到 rc.2 而 peer 下限不动**：rc.1 → rc.2 的 delta 里没有任何触及本插件的面（零 `packages/api|host|session|agent` 变更，真正的代码改动只有消息反馈弹窗、产物卡片 CSS、`CodeFileIcon` 的 SVG 数据拆分），`^0.1.5-rc.1` 天然容纳 rc.2，rc.1 用户无需升级即可用新版插件。0.1.5-alpha.2 用户停留在 **v0.19.0-alpha.1**（npm `alpha`）——rc 线的 delta 都很小，插件不再对 alpha 线做运行时兼容；0.1.2-rc.1 稳定线用户继续用 **v0.18.1**——0.1.5 的会话事件模型与文件打开漏斗都变了，插件不再对 0.1.2 做运行时兼容。发版：release.yml 按版本号是否含 `-` 自动选 `alpha`/`latest` dist-tag（0.19.1 无后缀 → `latest`；npm `alpha` 标签仍指向 `0.19.0-alpha.1`）。
 
 宿主契约（均经真机挂载冒烟 14/14 验证）：
 
@@ -33,12 +33,12 @@
 2. **Remote gateway 斜杠 RPC（唯一方言）**：`POST /api/workspace/create`，payload 恰为 `{args: {...}}`，**args 按控制器 TS 参数名包装**（`workspace/create`、`session/create` → `{args:{request:{...}}}`；`session/list` 参数名 `_request` **不可省略**——`{}` 也被拒 `args fields do not match the descriptor`）；envelope `method` 与路径一致，点分路径 404。请求由 `tests/e2e/host-protocol.ts` 的 `rpcAttempt` 构造、`tests/e2e-host-protocol.spec.ts` 锁定；要调新方法先在真机验参数名再进 `RPC_ARGS_KEY`。
 3. **`MarkdownText` labels 嵌套契约**：必填 `labels: { code: { copyLabel, copiedLabel }, footnotes }`（漏传回退硬编码中文）。四个渲染点（mermaid.tsx / MarkdownHtml.tsx / TextEditor.tsx / SideChatView.tsx）统一走 `src/client/markdown-labels.tsx` 的 `markdownTextProps()`。
 4. **侧边对话转录走自有路由，不碰客户端宿主 RPC**：`ctx.connection.api`（含 `sessions.history`）在 alpha.1 整体移除，继任 `session/follow|page` 又对 `origin:'subagent'` 会话强制 subagent 地址（普通 `{kind:'session'}` 被 `agent-busy` 拒）且分页 `throughSeq` 不得超当前游标。转录因此由 **`sidechat.events`** 插件路由供给（`src/sidechat-routes.ts`：live 读 `agent.session.snapshotEvents()`、冷读 `sessionPersistence.inspect`，服务端 `session/end-seed` 切割 + `afterSeq` 增量）；`ctx.connection` 镜像与 inject 已删。**0.1.5 起实时增量不在日志里**：`assistant/chunk` 事件被删除，进行中的模型增量改由 `agent/assistant-stream` 瞬时帧发布（`start` / `chunk` / `end`，不入会话日志），结算时才落 `assistant/message`（内嵌 `stream`）或 `assistant/attempt`（失败尝试，内嵌 `stream`）。插件在宿主侧 `src/assistant-live.ts` 折叠这些帧成有界缓冲，`sidechat.events` 的 `live` 字段按「当前 attempt 全量、每次轮询替换」下发（不是增量），转录映射与继承快照都读它。设计见 [docs/plans/2026-08-20-sidechat-tab-design.md](docs/plans/2026-08-20-sidechat-tab-design.md) §10。
-5. **`dsh-settings` 无运行时 `settingsNamespace`**：命名空间合法性校验转为编译期模板字面量 `SettingsNamespaceInput`（小写字母开头 + `[a-z0-9-]` 尾部），`'dsh-better-sidebar'` 字面量直接过——宿主侧直接传常量（`src/index.ts` 的 settings inject）。
+5. **`dsh-settings` 无运行时 `settingsNamespace`**：命名空间合法性校验转为编译期模板字面量 `SettingsNamespaceInput`（小写字母开头 + `[a-z0-9-]` 尾部），`'dsh-apes-sidebar'` 字面量直接过——宿主侧直接传常量（`src/index.ts` 的 settings inject）。
 6. **`dsh-subagent` 的 `SUBAGENT_DESCRIPTOR_VERSION` 2 → 3**：sidechat 种子的 `subagent/descriptor` 版本由宿主包盖章，插件不硬编码；测试断言跟随常量（`tests/sidechat-routes.spec.ts`），勿钉字面量。
 7. **`@deepseek-ai/dsh-client-runtime` 包已消亡**（继任 seed 是裸名 `dsh-client-store`，无 `/client` 子路径）：peerDependencies、devDependencies、`dsh.client.inject`、chunk externals 白名单（`src/client/chunk-loader.ts` / `tsdown.config.ts` / `tests/chunk-loader.spec.ts` / `tests/manifest-consistency.spec.ts` 四处同步）均已无该条目。
 8. **e2e scratch profile 的 `minimumReleaseAgeExclude` 含 `'@deepseek-ai/*'`**（`scripts/e2e-mount.sh` / `e2e-aggregate-mount.sh`，与仓库根 `pnpm-workspace.yaml` 同策）：alpha 版本常在发布后 24h 内跑 lane，pnpm 11 的 `minimumReleaseAge` 默认会拒装新鲜包。
-9. **插件开发树的 dsh-* 传递 peer 需提升为 devDependencies**（alpha.3 首见）：`dsh-subagent` 等 npm 包把 `dsh-attachment` 等 dsh-* 姊妹包全部声明为 peerDependencies（由宿主 bundle 树统一提供，宿主侧无此问题），插件仓库若只直接依赖其中一部分，其余 peer 在 pnpm 下会解析到树上残留的旧版——如 `dsh-attachment@0.1.1-rc.1` 缺 `admitPromptContent` 导出、`dsh-subagent` 产物 import 它时测试加载即崩。因此 devDependencies 需涵盖 dev 树实际触达的全部 peer（attachment / code-runtime / scope / session-projection / system-prompt / user-approval / util-time 七个即为此提升，与直接依赖同款精确钉版）；`@deepseek-ai/cordis` peer 自 alpha.3 起要求 `^4.0.2`（上游全线 peer 已升）。适配新 alpha 版本时先跑 `pnpm peers check`，把新失配的传递 peer 一并提升进 devDependencies。例外：**`dsh-client-locale` 的 peer/devDep 允许落后于基线**（alpha.5 时上游停在 0.1.2-alpha.3 未发新版）——peer 下限 `^0.1.2-alpha.3` 天然容纳同 tuple 的 alpha.5 运行时，此时保持旧钉版并在 `pnpm-workspace.yaml` 注明，待上游发版再追平；rc.1 起上游恢复发版，peer/devDep 已与基线一并钉 `0.1.2-rc.1`，该例外消除。**alpha.2 起还有一类：上游包自身的 `dependencies` 丢失**——`@deepseek-ai/dsh-client-ui-primitives@0.1.5-alpha.2` 的 manifest 不再声明任何 `dependencies`（alpha.1 声明了 19 个），但 `lib/*.js` 仍裸 import `anser` / `shiki` / `@shikijs/langs/*` / `mdast-util-*` / `micromark-*` / `katex`。宿主由预构建前端 bundle 满足，独立安装的 dev/test 树不会——vitest 一碰 primitives 就 `Cannot find package 'anser'`。此时把 alpha.1 声明的同一组版本提升进 devDependencies（`clsx` 已在 dependencies 无需重复）。
-10. **右侧栏是 DSH 原生栏，插件只提供 tab 类型**：聊天里一切文件打开（工具行 / 产物行 / 正文提及 / 行内代码路径）统一走 `ctx.sidebarRight.openResource(fileAddressFor(sessionId, cwd, path))`（`packages/client/ui-chat/src/client/apply.ts` 是唯一调用点），`remote.session.openWorkspacePath` 在 0.1.5 客户端已无调用者，插件的 openpath 拦截随之删除。插件的每个 `TabDescriptor` 注册成原生 tab 类型（`kind = descriptor.id`，`extension` 带）+ 原生 tab 体（`sidebar.right.pane.tab` keyed 槽，key = `dsh-better-sidebar:<id>`）；`editor` 类型同时认领 `dsh-resource://file/**`（压过内置 `text` 的 `fallback`），并接管内置 `files` 页面 kind（`openTab('files')` 打开插件文件树，注销即复位）。`ctx.sidebarRight.openTab/openResource/close` 只对**在屏会话**写入；跨会话用具体类上的 `openTabIn/openResourceIn/closeIn`（不在 `ISidebarRight` 接口里，需结构化探测），目标会话未挂载时排队到上屏重放（`src/client/native/surface.ts`）。原生 tab 的插件侧状态（合成 `SidebarTab`、树展开集合、实例编号）在 `src/client/native/tab-adapter.tsx`；原生布局只在内存，不做持久化。**注册必须等服务、不能等槽声明**：原生栏先声明 `sidebar.right.pane.tab` 再 `provide('sidebarRightTabs')`，真机 profile（web，0.1.5-alpha.1）上槽声明回调里 `ctx.get('sidebarRightTabs')` 仍是 undefined（实测 3 秒后才出现），按槽触发注册会静默什么都不注册且永不重试——用 `ctx.inject(['sidebarRightTabs'], cb)` 驱动类型注册（`tests/native-surface.spec.ts` 以「槽先触发、服务后到达」的顺序守护），槽声明只用来挂 tab 体。指南 §0 列了全部行为差异。**alpha.2 起（v0.19.0-alpha.1）**：指南条目删除 `description`（原生指南渲染成「图标+标题」胶囊），插件随之下线 `TabDescriptor.description` 与 6 个 `guideDesc*` 词条；新建标签页的默认页改为从注册表选（恰好 1 个指南条目 → 直接开它，0 或 ≥2 → 开指南），`revealIfOpened` 对「页面」在同一 pane 内强制去重。原生 tab 体宿主 `.paneBody` 是**有确定高度的块级滚动容器**（非 flex 容器），native 适配层因此给每个 tab 体包一层 `height:100%` 的列 flex 宿主（`sidebar.module.css` 的 `.nativeTabHost`），tab 组件根继续用 `flex:1`/`height:100%`——否则根盒塌成内容高度，sidechat 的输入框就贴不到面板底。全局面板（根级 `main` keyed 槽 + `sidebar.panellist` + `ctx.layout.selectPanel/beginNavigation`、`rightbar` 改根级并新增 `rightbar.session`）插件**不接入**，只做兼容。底部工作台的中心列锚点改认 `[data-slot="main.conversation"]`（并跳过 `display: contents` 祖先，同时保留 alpha.1 的 `[data-slot="conversation"]`）；文件地址语法跟随 alpha.2（`fileAddressFor` 一律 session 作用域、绝对路径保留前导 `/`、`parseFileAddress` 前缀解析并去 `?`/`#`）。
+9. **插件开发树的 dsh-* 传递 peer 需提升为 devDependencies**（alpha.3 首见）：`dsh-subagent` 等 npm 包把 `dsh-attachment` 等 dsh-* 姊妹包全部声明为 peerDependencies（由宿主 bundle 树统一提供，宿主侧无此问题），插件仓库若只直接依赖其中一部分，其余 peer 在 pnpm 下会解析到树上残留的旧版——如 `dsh-attachment@0.1.1-rc.1` 缺 `admitPromptContent` 导出、`dsh-subagent` 产物 import 它时测试加载即崩。因此 devDependencies 需涵盖 dev 树实际触达的全部 peer（attachment / code-runtime / scope / session-projection / system-prompt / user-approval / util-time 七个即为此提升，与直接依赖同款精确钉版）；`@deepseek-ai/cordis` peer 自 alpha.3 起要求 `^4.0.2`（上游全线 peer 已升）。适配新 alpha 版本时先跑 `pnpm peers check`，把新失配的传递 peer 一并提升进 devDependencies。例外：**`dsh-client-locale` 的 peer/devDep 允许落后于基线**（alpha.5 时上游停在 0.1.2-alpha.3 未发新版）——peer 下限 `^0.1.2-alpha.3` 天然容纳同 tuple 的 alpha.5 运行时，此时保持旧钉版并在 `pnpm-workspace.yaml` 注明，待上游发版再追平；rc.1 起上游恢复发版，该包回到与 DSH 同 tuple（0.1.2-rc.1 → 0.1.5-rc.1，peer 下限 `^0.1.5-rc.1`），该例外消除。**alpha.2 起还有一类：上游包自身的 `dependencies` 丢失**——`@deepseek-ai/dsh-client-ui-primitives@0.1.5-alpha.2` 的 manifest 不再声明任何 `dependencies`（alpha.1 声明了 19 个），但 `lib/*.js` 仍裸 import `anser` / `shiki` / `@shikijs/langs/*` / `mdast-util-*` / `micromark-*` / `katex`。宿主由预构建前端 bundle 满足，独立安装的 dev/test 树不会——vitest 一碰 primitives 就 `Cannot find package 'anser'`。此时把 alpha.1 声明的同一组版本提升进 devDependencies（`clsx` 已在 dependencies 无需重复）。**rc.1 复查：`@deepseek-ai/dsh-client-ui-primitives@0.1.5-rc.1` 仍不声明任何 `dependencies`，bundle 仍裸 import 同一组包**（rc.2 同：只把 `CodeFileIcon` 的 SVG 数据拆进了新文件，无 `dependencies`）——这组提升不得回退，`pnpm peers check` / 单测一旦报 `Cannot find package 'anser'` 即是有人回退了。
+10. **右侧栏是 DSH 原生栏，插件只提供 tab 类型**：聊天里一切文件打开（工具行 / 产物行 / 正文提及 / 行内代码路径）统一走 `ctx.sidebarRight.openResource(fileAddressFor(sessionId, cwd, path))`（`packages/client/ui-chat/src/client/apply.ts` 是唯一调用点），`remote.session.openWorkspacePath` 在 0.1.5 客户端已无调用者，插件的 openpath 拦截随之删除。插件的每个 `TabDescriptor` 注册成原生 tab 类型（`kind = descriptor.id`，`extension` 带）+ 原生 tab 体（`sidebar.right.pane.tab` keyed 槽，key = `dsh-apes-sidebar:<id>`）；`editor` 类型同时认领 `dsh-resource://file/**`（压过内置 `text` 的 `fallback`），并接管内置 `files` 页面 kind（`openTab('files')` 打开插件文件树，注销即复位）。`ctx.sidebarRight.openTab/openResource/close` 只对**在屏会话**写入；跨会话用具体类上的 `openTabIn/openResourceIn/closeIn`（不在 `ISidebarRight` 接口里，需结构化探测），目标会话未挂载时排队到上屏重放（`src/client/native/surface.ts`）。原生 tab 的插件侧状态（合成 `SidebarTab`、树展开集合、实例编号）在 `src/client/native/tab-adapter.tsx`；原生布局只在内存，不做持久化。**注册必须等服务、不能等槽声明**：原生栏先声明 `sidebar.right.pane.tab` 再 `provide('sidebarRightTabs')`，真机 profile（web，0.1.5-alpha.1）上槽声明回调里 `ctx.get('sidebarRightTabs')` 仍是 undefined（实测 3 秒后才出现），按槽触发注册会静默什么都不注册且永不重试——用 `ctx.inject(['sidebarRightTabs'], cb)` 驱动类型注册（`tests/native-surface.spec.ts` 以「槽先触发、服务后到达」的顺序守护），槽声明只用来挂 tab 体。指南 §0 列了全部行为差异。**alpha.2 起（v0.19.0-alpha.1）**：指南条目一度改成「图标+标题」胶囊、`TabDescriptor.description` 随之下线，新建标签页的默认页改为从注册表选（恰好 1 个指南条目 → 直接开它，0 或 ≥2 → 开指南），`revealIfOpened` 对「页面」在同一 pane 内强制去重。原生 tab 体宿主 `.paneBody` 是**有确定高度的块级滚动容器**（非 flex 容器），native 适配层因此给每个 tab 体包一层 `height:100%` 的列 flex 宿主（`sidebar.module.css` 的 `.nativeTabHost`），tab 组件根继续用 `flex:1`/`height:100%`——否则根盒塌成内容高度，sidechat 的输入框就贴不到面板底。全局面板（根级 `main` keyed 槽 + `sidebar.panellist` + `ctx.layout.selectPanel/beginNavigation`、`rightbar` 改根级并新增 `rightbar.session`）插件**不接入**，只做兼容。底部工作台的中心列锚点改认 `[data-slot="main.conversation"]`（并跳过 `display: contents` 祖先，同时保留 alpha.1 的 `[data-slot="conversation"]`）；文件地址语法跟随 alpha.2（`fileAddressFor` 一律 session 作用域、绝对路径保留前导 `/`、`parseFileAddress` 前缀解析并去 `?`/`#`）。**rc.1 起（v0.19.0）**：`SidebarRightGuideEntry.description` 回归（可选），插件恢复 `TabDescriptor.description`（六个内置类型各声明一条说明，`guideDesc*` 词条回到 20 份词典），但**宿主的原生指南只在列出的条目 ≤ 4 条时渲染说明**（上游 `MAX_DESCRIBED_ENTRIES = 4`；更长的列表是整列丢弃，不是截断）——插件默认贡献 6 个 guide 条目（文件 / 文件变动 / 任务管理 / 侧边对话 / 终端 / 浏览器），所以**默认组合下说明不渲染**，只有读者在插件设置页关掉足够多 tab 类型、把 guide 压到 ≤ 4 条时才出现；插件**不恢复**旧的 `nativeGuideDesc` 通用兜底句（宿主自己没有兜底，通用句是噪音），没声明说明的 descriptor 就不发 `description` 字段；条目缺 `icon` 时由宿主补方块占位。
 11. **自定义种子必须带 fork 标记对（`meta.isSeeded: true` + `inheritedEventCount`）**：dsh-session 契约「只给 seed 不标 isSeeded，种子算重放历史而非继承前缀」——缺标记时 `Session.ownEvents()` 含整个种子，子会话的 inbox 折（`inboxProjectionDefinition`，0.1.5 起 `@deepseek-ai/dsh-agent` 只导出 `Inbox` 接口，实现是该投影）重放种子里的 `agent/inbox/spliced`，**继承父会话切割时刻未领取的 inbox 输入**（排队用户消息 next-turn、长回合中工具结果上下文/steering next-step——后者即「上下文很长时侧边对话先把之前的 User msg 发出去」的根因，幽灵消息排在 boundary 之前最先发给模型）。宿主 `session.fork`（api-session-controller）的调用即规范形态；回归由 `tests/sidechat-seed-validation.spec.ts`（真实 `Session.create` + 对 `ownEvents()` 跑 inbox 折）守护。0.1.5 复评：无更优雅的 sidechat 宿主 API（`ContinuableStartSpec` 仍无 seed 字段），`AgentRegistry.create` 接缝补齐标记即为规范用法；`Session.create` 的 header `version` 必须用 `SESSION_FORMAT_VERSION`（0.1.5 是 `3` 字面量类型），勿钉 `0`。
 
 ---
@@ -59,9 +59,11 @@
 - **构建纯度门**：client bundle 禁止 value-import `@dsh-external/*` 或非白名单 `@deepseek-ai/*`（`tsdown.config.ts` 拦截）；`import type {}` 被擦除不触发——类型可共享，运行时符号不行；跨插件交互走 `ctx.betterSidebar` 方法调用。
 - **懒加载 chunk**：重依赖（xterm/CodeMirror/mermaid）在独立 bundle（`lib/client-<name>.js`），经 `/sidebar/bundle` 按需下发、`globalThis.__dshChunks__` 物化（`src/client/chunk-loader.ts`），**核心 bundle 禁止静态 import `src/client/chunks/*`**。
 - **i18n**：词典在 `betterSidebar` 命名空间，跟随 DSH `ctx.locale`；**新增 zh key 必须同步 `src/client/locales-ja.ts` 的 ja 翻译**（否则 ja 下回退 en）。渲染 `MarkdownText` 必须经 `markdownTextProps()`（§3 第 3 条）。
-- **皮肤契约**：视觉值只消费 `--dsw-alias-*` / `--dsw-font-*` / `--ds-*` 令牌，无硬编码颜色；契约全文与 titleBar 四方案模型见[指南 §12](docs/external-plugin-guide.md)，改动必须同步该节与 `tests/theme.spec.ts`。
+- **皮肤契约**：视觉值只消费 `--dsw-alias-*` / `--dsw-font-*` / `--ds-*` 令牌，无硬编码颜色，**插件没有任何豁免面**——文件/文件夹图标是 DSH 官方 `FileTypeIcon` 的图形（宿主自己的调色板），插件画的每个 glyph（含内置 tab 彩色图标）颜色都来自令牌；`tests/theme.spec.ts` 同时守护「图标模块零颜色字面量」「样式表每条 `color` 解析到令牌」「没有图标数据被做成 chunk」。契约全文与 titleBar 四方案模型见[指南 §12](docs/external-plugin-guide.md)，改动必须同步该节与 `tests/theme.spec.ts`。
 - **契约反向引用**：皮肤契约被 `src/client/shell-presets.ts`、`tests/e2e/mount.e2e.ts` 的注释以「指南 §12」引用——调整指南章节结构时同步检查这两处。
 - **接入 API 即文档**：`src/client/service.ts` 与 `src/client/builtins/` 的任何行为变更，必须同步 [docs/external-plugin-guide.md](docs/external-plugin-guide.md)（唯一权威接入文档，不再双份维护）。
+- **文件/文件夹图标**：回退链是「具体 `names`/`exts` 注册 → catch-all（`exts: []`）→ 宿主 `FileTypeIcon`」。插件**不持有**扩展名表、图标数据或图标 chunk（#429 的 563 条数据与 `fileIconTheme` 开关在 rc.2 适配时删除，因为宿主已导出官方图形）。**语义雷区**：宿主分类器覆盖任意路径，所以注册 `exts: []` 会接管所有未具体命中的行——只想补几个类型的插件必须用 `exts`/`names`。
+- **内置 tab 图标**：六个内置类型与 diff 视图的 glyph 集中在 `src/client/builtins/tab-icons.tsx`（颜色在 `tab-icons.module.css`，全部 `--dsw-alias-*`），三处消费面自动同步：底部工作台 tab 条、原生指南胶囊、原生 tab 芯片。**原生芯片的图标是插件自己画的**——宿主的 `SidebarRightTabDefinition` 没有 icon 字段，但 `sidebar.right.pane.tab.title` 槽就是芯片内容（`NativeTabTitle` 渲染 `[glyph][title]`，glyph `aria-hidden` 以免改可访问名）。
 
 ---
 

Makefile

@@ -1,4 +1,4 @@
-# dsh-better-sidebar 命令面薄封装：目标仅转发 package.json scripts（唯一事实源），
+# dsh-apes-sidebar 命令面薄封装：目标仅转发 package.json scripts（唯一事实源），
 # 新增/改名 script 不需要动这里；本文件只补目标发现（help）与 CI 门禁聚合
 # （check / mount / mount-aggregate / registry）。
 

README.md

@@ -1,16 +1,34 @@
-# dsh-better-sidebar
+# dsh-apes-sidebar
+
+> [!NOTE]
+> **Fork notice** — 本项目是 [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar) 的 fork，
+> 基线 **upstream v0.19.1**（commit `8753096`，MIT）。
+>
+> - **上游 v0.18.0 → v0.19.1 的关键变化**：v0.19.0-alpha.1 起，插件的内容**注册进 DSH 原生右侧栏**
+>   （`src/client/native/`）——不再自绘第二套右侧面板与开关按钮。这正是本 fork 此前"窗口里有两套侧边栏
+>   与两套开关"的根因；升到 v0.19.1 后**只剩一套**。
+> - **本 fork 的增量**：`src/client/apes/` 下的 3 个信息层 tab（`apes:agents` 智能体 / `apes:apps` 应用 /
+>   `apes:profile` 画像），按 DSH 标准 `TabDescriptor` 接口注册——因此它们会自动获得上游原生适配层
+>   的全部待遇（进原生 guide、tab 芯片图标、开合与分栏）。
+> - 版本线独立于上游：`1.2.0`（fork）。上游历史版本见其 CHANGELOG。
+> - **📚 项目百科**（需求分析 → 系统架构 → 功能说明 → 部署指南 → 运维手册 → 故障排查 → 开发与测试）：
+>   <https://gitea.apescale.com/figmar/apes-sidebar/wiki>　源文件在仓库 `docs/wiki/`，
+>   改完用 `bash scripts/push-wiki.sh` 一条命令发布。
+
+> [!IMPORTANT]
+> **已适配 DSH 原生侧边栏 API**（v0.19.0 起，DSH `0.1.5-rc.1+`）：右列就是 DSH 自己的右侧栏——插件的每个 tab 类型与 tab 体通过 `ctx.sidebarRightTabs` / `ctx.sidebarRight` 注册与打开，聊天里的文件打开统一走 `ctx.sidebarRight.openResource('dsh-resource://file/…')`，插件**不再自绘右侧面板**（旧的浮窗能力同步移除）。自绘的底部工作台与开放给其他插件的 `ctx.betterSidebar` 服务保持不变，接入方式见[插件接入指南](docs/external-plugin-guide.md)。
 
 <!-- Hero -->
 <div align="center">
   <b style="font-size: 1.15em;">一个服务化的侧边栏框架，一套开箱即用的完整工作台</b><br /><br />
-  <a href="https://www.npmjs.com/package/dsh-better-sidebar"><img alt="npm version" src="https://img.shields.io/npm/v/dsh-better-sidebar" /></a>
-  <a href="https://www.npmjs.com/package/dsh-better-sidebar"><img alt="npm downloads" src="https://img.shields.io/npm/dm/dsh-better-sidebar" /></a>
+  <a href="https://www.npmjs.com/package/dsh-apes-sidebar"><img alt="npm version" src="https://img.shields.io/npm/v/dsh-apes-sidebar" /></a>
+  <a href="https://www.npmjs.com/package/dsh-apes-sidebar"><img alt="npm downloads" src="https://img.shields.io/npm/dm/dsh-apes-sidebar" /></a>
   <a href="https://github.com/omdsh-dev/DSH-better-sidebar/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/omdsh-dev/DSH-better-sidebar/actions/workflows/ci.yml/badge.svg" /></a>
   <a href="https://github.com/omdsh-dev/DSH-better-sidebar/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/omdsh-dev/DSH-better-sidebar" /></a>
   <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg" /></a>
   <a href="https://dshfind.com/zh/plugins/omdsh-dev/DSH-better-sidebar?ref=badge"><img alt="dshfind" src="https://dshfind.com/api/badge/omdsh-dev/DSH-better-sidebar?lang=zh" /></a><br /><br />
-  <a href="https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions"><img alt="支持的 DSH 版本（v0.18.1 正式版）：0.1.2-rc.1+" src="https://img.shields.io/badge/DSH-0.1.2--rc.1%2B-4d6bfe" /></a>
-  <a href="https://github.com/topics/dsh-better-sidebar"><img alt="插件生态：GitHub topic dsh-better-sidebar" src="https://img.shields.io/badge/%E6%8F%92%E4%BB%B6%E7%94%9F%E6%80%81-topic%20dsh--better--sidebar-4d6bfe" /></a><br /><br />
+  <a href="https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions"><img alt="支持的 DSH 版本（v0.19.1 正式版）：0.1.5-rc.1+（已在 0.1.5-rc.2 上验证）" src="https://img.shields.io/badge/DSH-0.1.5--rc.1%2B_%28verified_rc.2%29-4d6bfe" /></a>
+  <a href="https://github.com/topics/dsh-apes-sidebar"><img alt="插件生态：GitHub topic dsh-apes-sidebar" src="https://img.shields.io/badge/%E6%8F%92%E4%BB%B6%E7%94%9F%E6%80%81-topic%20dsh--better--sidebar-4d6bfe" /></a><br /><br />
   <img alt="文件管理" src="https://img.shields.io/badge/-文件管理-4d6bfe" /> <img alt="编辑预览" src="https://img.shields.io/badge/-编辑预览-4d6bfe" /> <img alt="内嵌浏览器" src="https://img.shields.io/badge/-内嵌浏览器-4d6bfe" /> <img alt="真实终端" src="https://img.shields.io/badge/-真实终端-4d6bfe" /> <img alt="文件变动" src="https://img.shields.io/badge/-文件变动-4d6bfe" /> <img alt="后台任务" src="https://img.shields.io/badge/-后台任务-4d6bfe" /> <img alt="侧边对话" src="https://img.shields.io/badge/-侧边对话-4d6bfe" /> <img alt="插件接入" src="https://img.shields.io/badge/-插件接入-4d6bfe" /><br /><br />
   <b>右侧栏 + 底部面板双工作台</b>，并把 <code>ctx.betterSidebar</code> 服务开放给所有插件——<br />
   通过 <code>registerTab</code> / <code>registerFileViewer</code> 注册新的侧边栏页面与文件预览器。
@@ -21,7 +39,7 @@
 </div>
 
 <div align="center">
-  <img alt="dsh-better-sidebar 工作台截图" src="https://github.com/user-attachments/assets/991c4b70-d45a-461f-a8c8-0a28b4218e60" />
+  <img alt="dsh-apes-sidebar 工作台截图" src="https://github.com/user-attachments/assets/991c4b70-d45a-461f-a8c8-0a28b4218e60" />
   <video src="https://github.com/user-attachments/assets/23187822-047e-45cc-b480-fe997bd55b86" muted autoplay loop playsinline controls width="100%"></video>
 </div>
 
@@ -40,7 +58,7 @@
 
 ## ✨ 功能一览
 
-- **🗂️ 文件工作台**：资源管理器（懒加载目录树；软链接按目标类型展示——目录软链接可展开、失效链接标红）+ CodeMirror 编辑器；图片 / Markdown（含 Mermaid 图表，strict 安全渲染 + 点击放大；README 级内嵌 HTML——徽章墙 / `<details>` 折叠 / 表格内联标签经 DOMPurify 消毒真实渲染；浮动目录大纲一键跳转）/ HTML / PDF
+- **🗂️ 文件工作台**：资源管理器（懒加载目录树；软链接按目标类型展示——目录软链接可展开、失效链接标红；文件树与文件 tab 按扩展名显示图标——markdown / 图片 / PDF / 代码 / 配置 / 压缩包等各有 glyph，插件可经 `registerFileIcon` 注册自定义图标与目录图标）+ CodeMirror 编辑器；图片 / Markdown（含 Mermaid 图表，strict 安全渲染 + 点击放大；README 级内嵌 HTML——徽章墙 / `<details>` 折叠 / 表格内联标签经 DOMPurify 消毒真实渲染；浮动目录大纲一键跳转）/ HTML / PDF
 - **🌐 内嵌浏览器**：多开网页 tab，后退 / 前进 / 刷新；内容运行在沙箱 iframe；外链默认按协议分流——HTTP 在侧边栏打开、HTTPS 走系统浏览器（设置页可分别调整）
 - **💻 真实终端**：xterm.js + node-pty 真实 shell，断线重连回放；可选为模型注入 `terminal_*` 工具
 - **📂 模型侧边栏打开（可选）**：全局设置开启后注入 `sidebar_open` 工具——模型可主动在侧边栏打开文件 / 文件夹（树以该目录为根）/ HTTP(S) 网页
@@ -61,14 +79,14 @@
 **前置**：已装好 DSH（`dsh web` 能正常运行），Node.js ≥ 20、pnpm ≥ 10。
 
 **支持的 DSH 版本**：
-<a href="https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions"><img alt="支持的 DSH 版本（v0.18.1 正式版）：0.1.2-rc.1+" src="https://img.shields.io/badge/DSH-0.1.2--rc.1%2B-4d6bfe" /></a>
+<a href="https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions"><img alt="支持的 DSH 版本（v0.19.1 正式版）：0.1.5-rc.1+（已在 0.1.5-rc.2 上验证）" src="https://img.shields.io/badge/DSH-0.1.5--rc.1%2B_%28verified_rc.2%29-4d6bfe" /></a>
 
-> 📌 **正式版**：`v0.18.0` 起适配 DSH **0.1.2-rc.1+**（npm dist-tag `latest`），不再支持 0.1.0-rc.8 ~ 0.1.1-rc.2——DSH stable（≤ 0.1.1-rc.2）用户请固定安装 `dsh-better-sidebar@0.17.1`（`@latest` 已由 v0.18.0 接管）；停留在 0.1.2-alpha.x 的宿主请先升级 DSH，或继续用 `dsh-better-sidebar@alpha`（v0.18.0-alpha.0）。
+> 📌 **正式版**：`v0.19.0` 起适配 DSH **0.1.5-rc.1+**（npm dist-tag `latest`；`v0.19.1` 已在 **0.1.5-rc.2** 上完成真机挂载验证，rc.1 用户无需升级即可用本版——peer 下限仍是 `^0.1.5-rc.1`）。仍停在 DSH 0.1.5-alpha.2 的用户请固定安装 `dsh-apes-sidebar@0.19.0-alpha.1`；0.1.2-rc.1 稳定线用户继续用 `dsh-apes-sidebar@0.18.x`；DSH ≤ 0.1.1-rc.2 请用 `dsh-apes-sidebar@0.17.1`。
 
 ```sh
-dsh plugin --profile web add dsh-better-sidebar@latest   # 首次会因 pnpm 11 拦截 node-pty 构建脚本而失败（依赖已写入）
+dsh plugin --profile web add dsh-apes-sidebar@latest   # 首次会因 pnpm 11 拦截 node-pty 构建脚本而失败（依赖已写入）
 cd ~/.dsh/profiles/web && pnpm approve-builds --all      # 放行构建脚本（自动重跑安装）
-dsh plugin --profile web add dsh-better-sidebar@latest   # 重跑即成功
+dsh plugin --profile web add dsh-apes-sidebar@latest   # 重跑即成功
 ```
 
 装完**硬刷新浏览器**（Cmd/Ctrl+Shift+R）即可看到侧边栏（DSH 对 client 改动热加载，无需重启；仅 host 半更新时需要重启）。
@@ -76,10 +94,10 @@ dsh plugin --profile web add dsh-better-sidebar@latest   # 重跑即成功
 **方式二：让 DSH 自己装**——把下面这段提示词发给任意一个 DSH 会话：
 
 ```text
-帮我安装 dsh-better-sidebar 插件（DSH 侧边栏工作台），步骤：
-1. 执行 dsh plugin --profile web add dsh-better-sidebar@latest（首次会被 pnpm 11 拦截 node-pty 构建脚本而失败，属正常）
+帮我安装 dsh-apes-sidebar 插件（DSH 侧边栏工作台），步骤：
+1. 执行 dsh plugin --profile web add dsh-apes-sidebar@latest（首次会被 pnpm 11 拦截 node-pty 构建脚本而失败，属正常）
 2. 在 ~/.dsh/profiles/web 下执行 pnpm approve-builds --all（放行构建脚本，会自动重跑安装）
-3. 再次执行 dsh plugin --profile web add dsh-better-sidebar@latest
+3. 再次执行 dsh plugin --profile web add dsh-apes-sidebar@latest
 4. 完成后提醒我硬刷新浏览器（Cmd/Ctrl+Shift+R）
 遇到报错先查 https://github.com/omdsh-dev/DSH-better-sidebar README 的常见问题表。
 ```
@@ -90,7 +108,7 @@ dsh plugin --profile web add dsh-better-sidebar@latest   # 重跑即成功
 <summary><b>更新</b></summary>
 
 ```sh
-dsh plugin --profile web add dsh-better-sidebar@latest
+dsh plugin --profile web add dsh-apes-sidebar@latest
 ```
 
 也可把 `~/.dsh/profiles/web/package.json` 里的版本号改高后 `pnpm install`。改完**硬刷新浏览器**（Cmd/Ctrl+Shift+R）即可（client 改动无需重启 DSH）。
@@ -105,10 +123,10 @@ dsh plugin --profile web add dsh-better-sidebar@latest
 | 报 `Ignored build scripts` | pnpm 11 拦截构建脚本。在 profile 目录（`~/.dsh/profiles/web`）跑 `pnpm approve-builds --all`。 |
 | 报 `minimum release age` / 版本不足 24h | 装的版本发布不足 24 小时。等 24h 或重跑一次（pnpm 会自动补 `minimumReleaseAgeExclude`）。 |
 | 报「找不到 profile 目录」 | 先跑一次 `dsh web`，让它初始化 `~/.dsh/profiles/web`。 |
-| 页面出现**两个侧边栏** | 双挂载。旧的手动挂载行：`~/.dsh/profiles/web/cordis.patch.yml` 还留着 `- insert: ... better-sidebar ...`，删掉那段（同 id 重复挂载 loader 会直接报 `duplicate loader entry id`）。聚合包（如 `@linxin666/dsh-web-ui-all`）以**不同 id** 挂载本包时，0.13.x 起插件自身 bundle patch 会自动退让（检测到已有启用中的同包名挂载就不挂自己），无需手动处理；若仍双挂载，先确认聚合包的 bundle 顺序在 `dsh-better-sidebar` 之前。 |
+| 页面出现**两个侧边栏** | 双挂载。旧的手动挂载行：`~/.dsh/profiles/web/cordis.patch.yml` 还留着 `- insert: ... better-sidebar ...`，删掉那段（同 id 重复挂载 loader 会直接报 `duplicate loader entry id`）。聚合包（如 `@linxin666/dsh-web-ui-all`）以**不同 id** 挂载本包时，0.13.x 起插件自身 bundle patch 会自动退让（检测到已有启用中的同包名挂载就不挂自己），无需手动处理；若仍双挂载，先确认聚合包的 bundle 顺序在 `dsh-apes-sidebar` 之前。 |
 | Windows 下终端无法使用 | `node-pty` 依赖预编译二进制；若当前 Node 版本没有对应产物，需装编译工具链（VS Build Tools）。主流 Node 版本一般已有预编译。 |
 | 终端提示「node-pty 加载失败」 | `node-pty` 安装缺失/损坏（如 pnpm 拦截了构建脚本）。终端横幅会给出修复命令：复制到 DSH 所在环境的终端/cmd 执行（在 `~/.dsh/profiles/web` 下 `pnpm approve-builds --all && pnpm rebuild node-pty`），完成后重启 DSH 并点重试。插件与 DSH 核心使用同一 `node-pty@^1.1.0`，修复后两者同步恢复。 |
-| 提示 `dsh: command not found` | 先安装 DSH；或直接用 `npx -y --package @deepseek-ai/dsh dsh plugin --profile web add dsh-better-sidebar@latest`。 |
+| 提示 `dsh: command not found` | 先安装 DSH；或直接用 `npx -y --package @deepseek-ai/dsh dsh plugin --profile web add dsh-apes-sidebar@latest`。 |
 
 </details>
 
@@ -120,11 +138,11 @@ dsh plugin --profile web add dsh-better-sidebar@latest
 ```text
 1. git clone https://github.com/omdsh-dev/DSH-better-sidebar.git ~/Code/DSH-better-sidebar
    cd ~/Code/DSH-better-sidebar && pnpm install && pnpm build
-2. ~/.dsh/profiles/web/package.json 的 dependencies 写 "dsh-better-sidebar": "link:<克隆目录绝对路径>"
+2. ~/.dsh/profiles/web/package.json 的 dependencies 写 "dsh-apes-sidebar": "link:<克隆目录绝对路径>"
 3. ~/.dsh/profiles/web/cordis.patch.yml 追加挂载行（需要指定终端 shell 时，在行内加 `config.shell`；`config.shellArgs` 可带参启动，非空时替换默认的 `-l`。不填则自动解析 `$SHELL` / 登录 shell / powershell.exe）：
    - insert:
        - id: better-sidebar
-         name: 'dsh-better-sidebar'
+         name: 'dsh-apes-sidebar'
          config:
            shell: /bin/zsh
            shellArgs:
@@ -134,7 +152,7 @@ dsh plugin --profile web add dsh-better-sidebar@latest
 5. 硬刷新浏览器（Cmd/Ctrl+Shift+R）即可看到效果（client 改动无需重启 DSH；host 半改动才需重启）
 ```
 
-更新：`git pull && pnpm install && pnpm build` → 硬刷新浏览器即可（client 改动热加载生效，无需重启 DSH；host 半改动才需重启）。切回 npm 通道时，把依赖改回 `"dsh-better-sidebar": "^0.16.1"` 再 `pnpm install`。
+更新：`git pull && pnpm install && pnpm build` → 硬刷新浏览器即可（client 改动热加载生效，无需重启 DSH；host 半改动才需重启）。切回 npm 通道时，把依赖改回 `"dsh-apes-sidebar": "^0.16.1"` 再 `pnpm install`。
 
 </details>
 
@@ -148,7 +166,7 @@ git clone https://github.com/omdsh-dev/DSH-better-sidebar.git && cd DSH-better-s
 pnpm install && pnpm build
 node scripts/package-registry.mjs   # 组装 registry/ 暂存（含清单 + 产物 + README，不入库）
 dsh registry install ./registry     # 安装（默认禁用）
-dsh registry enable dsh-external/dsh-better-sidebar
+dsh registry enable dsh-external/dsh-apes-sidebar
 ```
 
 更新：`git pull && pnpm install && pnpm build` → `node scripts/package-registry.mjs` → `dsh registry uninstall/install/enable`。切换通道前先移除另一通道的挂载。
@@ -173,7 +191,7 @@ dsh registry enable dsh-external/dsh-better-sidebar
 `ctx.betterSidebar` 服务向所有插件开放两个扩展点：**`registerTab`（注册侧边栏页面）** 与 **`registerFileViewer`（注册文件预览器）**。内置的 8 tab + 6 viewer 与第三方插件走同一套 API，能力完全对等。
 
 ```ts
-import type {} from 'dsh-better-sidebar'  // 触发 ctx.betterSidebar 类型合并
+import type {} from 'dsh-apes-sidebar'  // 触发 ctx.betterSidebar 类型合并
 export const inject = ['betterSidebar']
 export function apply(ctx: Context) {
   ctx.effect(() => ctx.betterSidebar.registerTab({
@@ -187,7 +205,7 @@ export function apply(ctx: Context) {
 }
 ```
 
-GitHub topic [`dsh-better-sidebar`](https://github.com/topics/dsh-better-sidebar) 下已有 **28+ 生态插件**（持续增长中）：
+GitHub topic [`dsh-apes-sidebar`](https://github.com/topics/dsh-apes-sidebar) 下已有 **28+ 生态插件**（持续增长中）：
 
 <div align="center">
   <a href="https://github.com/user-attachments/assets/d4385b7e-aab4-425d-a5c4-2da5da81a34e"><img width="66%" alt="设置页「添加插件」弹窗：推荐插件目录 + 一键复制安装命令" src="https://github.com/user-attachments/assets/d4385b7e-aab4-425d-a5c4-2da5da81a34e" /></a><br />
@@ -210,7 +228,7 @@ GitHub topic [`dsh-better-sidebar`](https://github.com/topics/dsh-better-sidebar
 | [GULI-lab/DSH-element-source](https://github.com/GULI-lab/DSH-element-source) | <img alt="stars" src="https://img.shields.io/github/stars/GULI-lab/DSH-element-source?style=flat&color=4d6bfe" /> | 点击页面任意 UI 元素直达 Vue / React / Svelte / Angular 源码并送入会话 |
 | [Lzh3070/dsh-file-review-tab](https://github.com/Lzh3070/dsh-file-review-tab) | <img alt="stars" src="https://img.shields.io/github/stars/Lzh3070/dsh-file-review-tab?style=flat&color=4d6bfe" /> | 文件改动审查页：行级红绿 diff + 撤销 + chat 行深链 |
 | [yq04/dsh-git-remotes](https://github.com/yq04/dsh-git-remotes) | <img alt="stars" src="https://img.shields.io/github/stars/yq04/dsh-git-remotes?style=flat&color=4d6bfe" /> | Git 远程页：分支 / 上游 / ahead-behind，fetch 可 prune、ff-only pull、确认后 push |
-| [ztyhehe/dsh-better-sidebar-svn](https://github.com/ztyhehe/dsh-better-sidebar-svn) | <img alt="stars" src="https://img.shields.io/github/stars/ztyhehe/dsh-better-sidebar-svn?style=flat&color=4d6bfe" /> | SVN 源码管理页：status / diff / log / commit / update / revert / 冲突解决，与内置 Git 面板对称 |
+| [ztyhehe/dsh-apes-sidebar-svn](https://github.com/ztyhehe/dsh-apes-sidebar-svn) | <img alt="stars" src="https://img.shields.io/github/stars/ztyhehe/dsh-apes-sidebar-svn?style=flat&color=4d6bfe" /> | SVN 源码管理页：status / diff / log / commit / update / revert / 冲突解决，与内置 Git 面板对称 |
 | [Melody-max114/dsh-excel-panel](https://github.com/Melody-max114/dsh-excel-panel) | <img alt="stars" src="https://img.shields.io/github/stars/Melody-max114/dsh-excel-panel?style=flat&color=4d6bfe" /> | Excel 编辑页：xlsx 预览 / 编辑、公式实时计算、合并单元格、保存回原文件 |
 | [v587d/dsh-anysearch-refs](https://github.com/v587d/dsh-anysearch-refs) | <img alt="stars" src="https://img.shields.io/github/stars/v587d/dsh-anysearch-refs?style=flat&color=4d6bfe" /> | AnySearch 搜索结果引用卡片：搜索词、来源摘要、关键词高亮 |
 | [mlosun/dsh-docs-panel](https://github.com/mlosun/dsh-docs-panel) | <img alt="stars" src="https://img.shields.io/github/stars/mlosun/dsh-docs-panel?style=flat&color=4d6bfe" /> | 全局文档面板：随身 Markdown 笔记，任何工作区随时可读 |
@@ -223,7 +241,7 @@ GitHub topic [`dsh-better-sidebar`](https://github.com/topics/dsh-better-sidebar
 | [yq04/dsh-turn-review](https://github.com/yq04/dsh-turn-review) | <img alt="stars" src="https://img.shields.io/github/stars/yq04/dsh-turn-review?style=flat&color=4d6bfe" /> | 本轮审查：逐回合审查 agent 改动 |
 | [Ghz114514/dsh-refpics](https://github.com/Ghz114514/dsh-refpics) | <img alt="stars" src="https://img.shields.io/github/stars/Ghz114514/dsh-refpics?style=flat&color=4d6bfe" /> | Pinterest 风格参考图搜索：瀑布流、侧栏画板、下载与 Eagle 收藏 |
 | [yzlin499/dsh-yzlin499-easy-plugins](https://github.com/yzlin499/dsh-yzlin499-easy-plugins) | <img alt="stars" src="https://img.shields.io/github/stars/yzlin499/dsh-yzlin499-easy-plugins?style=flat&color=4d6bfe" /> | 实用小工具集（毛坯房 DSH 友好） |
-| [dong-victor/dsh-better-sidebar-starter](https://github.com/dong-victor/dsh-better-sidebar-starter) | <img alt="stars" src="https://img.shields.io/github/stars/dong-victor/dsh-better-sidebar-starter?style=flat&color=4d6bfe" /> | 运行配置页：IDEA 式 Run/Debug 配置（npm / springboot / python / custom）——一键启动、历史保存、WebSocket 实时日志（ANSI 彩色）、多实例并行、进程树跨平台杀死 |
+| [dong-victor/dsh-apes-sidebar-starter](https://github.com/dong-victor/dsh-apes-sidebar-starter) | <img alt="stars" src="https://img.shields.io/github/stars/dong-victor/dsh-apes-sidebar-starter?style=flat&color=4d6bfe" /> | 运行配置页：IDEA 式 Run/Debug 配置（npm / springboot / python / custom）——一键启动、历史保存、WebSocket 实时日志（ANSI 彩色）、多实例并行、进程树跨平台杀死 |
 | [baosfeng/my-dsh-plugins](https://github.com/baosfeng/my-dsh-plugins) | <img alt="stars" src="https://img.shields.io/github/stars/baosfeng/my-dsh-plugins?style=flat&color=4d6bfe" /> | 个人多插件合集（`dsh-file-activity`）：侧边栏文件活动页——记录文件读取 / 新增 / 修改历史与统计，按文件夹平铺，点击用原生预览打开 |
 | [Hoemr/dsh-better-overleaf](https://github.com/Hoemr/dsh-better-overleaf) | <img alt="stars" src="https://img.shields.io/github/stars/Hoemr/dsh-better-overleaf?style=flat&color=4d6bfe" /> | Overleaf 标签页：直连 CDP 浏览器登录（支持第三方 Chromium）、项目切换、工作区下 overleaf/ 目录本地 git 镜像与双向同步 |
 
@@ -238,7 +256,7 @@ GitHub topic [`dsh-better-sidebar`](https://github.com/topics/dsh-better-sidebar
 |---|---|---|
 | [HuanLinOTO/dsh-plugin-better-sidebar-plugin-office](https://github.com/HuanLinOTO/dsh-plugin-better-sidebar-plugin-office) | <img alt="stars" src="https://img.shields.io/github/stars/HuanLinOTO/dsh-plugin-better-sidebar-plugin-office?style=flat&color=4d6bfe" /> | Office 三件套预览（.docx / .xlsx / .pptx），独立 bundle 瘦身主体（官方推荐目录收录） |
 | [zemul/dsh-video-preview](https://github.com/zemul/dsh-video-preview) | <img alt="stars" src="https://img.shields.io/github/stars/zemul/dsh-video-preview?style=flat&color=4d6bfe" /> | 视频内联预览：.mp4 / .webm / .mov / .mkv / .avi，自带 /video 路由支持 HTTP Range 拖进度条 |
-| [dong-victor/dsh-better-sidebar-jupyter](https://github.com/dong-victor/dsh-better-sidebar-jupyter) | <img alt="stars" src="https://img.shields.io/github/stars/dong-victor/dsh-better-sidebar-jupyter?style=flat&color=4d6bfe" /> | `.ipynb` 可运行 Notebook 视图：懒启动 Python kernel、流式输出、保存回写 |
+| [dong-victor/dsh-apes-sidebar-jupyter](https://github.com/dong-victor/dsh-apes-sidebar-jupyter) | <img alt="stars" src="https://img.shields.io/github/stars/dong-victor/dsh-apes-sidebar-jupyter?style=flat&color=4d6bfe" /> | `.ipynb` 可运行 Notebook 视图：懒启动 Python kernel、流式输出、保存回写 |
 
 </details>
 
@@ -249,22 +267,54 @@ GitHub topic [`dsh-better-sidebar`](https://github.com/topics/dsh-better-sidebar
 
 | 插件 | ⭐ | 简介 |
 |---|---|---|
-| [eg-bole/dsh-better-sidebar-icons](https://github.com/eg-bole/dsh-better-sidebar-icons) | <img alt="stars" src="https://img.shields.io/github/stars/eg-bole/dsh-better-sidebar-icons?style=flat&color=4d6bfe" /> | VSCode 风格文件 / 文件夹图标主题：文件树与编辑器 Tab 换上熟悉的开发环境图标（vscode-icons 移植，纯 DOM 覆盖零侵入，安装 / 卸载零残留） |
-| [dong-victor/dsh-better-sidebar-terminal-plus](https://github.com/dong-victor/dsh-better-sidebar-terminal-plus) | <img alt="stars" src="https://img.shields.io/github/stars/dong-victor/dsh-better-sidebar-terminal-plus?style=flat&color=4d6bfe" /> | 终端增强：内嵌 Nerd Font 图标字体、修复 xterm 图标渲染、稳定终端 cwd |
+| [eg-bole/dsh-apes-sidebar-icons](https://github.com/eg-bole/dsh-apes-sidebar-icons) | <img alt="stars" src="https://img.shields.io/github/stars/eg-bole/dsh-apes-sidebar-icons?style=flat&color=4d6bfe" /> | VSCode 风格文件 / 文件夹图标主题：文件树与编辑器 Tab 换上熟悉的开发环境图标（vscode-icons 移植，纯 DOM 覆盖零侵入，安装 / 卸载零残留） |
+| [dong-victor/dsh-apes-sidebar-terminal-plus](https://github.com/dong-victor/dsh-apes-sidebar-terminal-plus) | <img alt="stars" src="https://img.shields.io/github/stars/dong-victor/dsh-apes-sidebar-terminal-plus?style=flat&color=4d6bfe" /> | 终端增强：内嵌 Nerd Font 图标字体、修复 xterm 图标渲染、稳定终端 cwd |
 | [Max-Null/dsh-sidebar-preview-select](https://github.com/Max-Null/dsh-sidebar-preview-select) | <img alt="stars" src="https://img.shields.io/github/stars/Max-Null/dsh-sidebar-preview-select?style=flat&color=4d6bfe" /> | 预览划选增强：侧边栏预览里划选文本 → 浮动「发送到会话」 |
 | [Hoemr/dsh-quicklook](https://github.com/Hoemr/dsh-quicklook) | <img alt="stars" src="https://img.shields.io/github/stars/Hoemr/dsh-quicklook?style=flat&color=4d6bfe" /> | QuickLook 式空格预览：活动文件标签页按 Space 全尺寸查看图片 / PDF / 文本，Space 或 Esc 关闭 |
 
 </details>
 
-> 📣 **上架你的插件**：给仓库打上 `dsh-better-sidebar` topic 即出现在 [topic 页](https://github.com/topics/dsh-better-sidebar)；再向 [`src/client/plugins-tabs.ts`](./src/client/plugins-tabs.ts) / [`src/client/plugins-viewers.ts`](./src/client/plugins-viewers.ts) 提一条 `PluginEntry` PR，即可进入设置页内置推荐目录（数据完整性由 `tests/plugin-list.spec.ts` 守护）。
+> 📣 **上架你的插件**：给仓库打上 `dsh-apes-sidebar` topic 即出现在 [topic 页](https://github.com/topics/dsh-apes-sidebar)；再向 [`src/client/plugins-tabs.ts`](./src/client/plugins-tabs.ts) / [`src/client/plugins-viewers.ts`](./src/client/plugins-viewers.ts) 提一条 `PluginEntry` PR，即可进入设置页内置推荐目录（数据完整性由 `tests/plugin-list.spec.ts` 守护）。
 
 ## 🆕 最近更新
 
-**支持的 DSH 版本**：<a href="https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions"><img alt="支持的 DSH 版本（v0.18.1 正式版）：0.1.2-rc.1+" src="https://img.shields.io/badge/DSH-0.1.2--rc.1%2B-4d6bfe" /></a> · 完整发布历史见 [Releases](https://github.com/omdsh-dev/DSH-better-sidebar/releases)
+**支持的 DSH 版本**：<a href="https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions"><img alt="支持的 DSH 版本（v0.19.1 正式版）：0.1.5-rc.1+（已在 0.1.5-rc.2 上验证）" src="https://img.shields.io/badge/DSH-0.1.5--rc.1%2B_%28verified_rc.2%29-4d6bfe" /></a> · 完整发布历史见 [Releases](https://github.com/omdsh-dev/DSH-better-sidebar/releases)
+
+### v0.19.1
+
+> 📌 **正式版**（npm `latest`，无 prerelease 后缀）：钉版推进到 **DSH 0.1.5-rc.2**（npm `next`），**peer 下限仍是 `^0.1.5-rc.1`**——rc.2 的上游 delta 里没有任何触及本插件的面（零 `packages/api|host|session|agent` 变更，真实代码改动只有消息反馈弹窗、产物卡片 CSS 与 `CodeFileIcon` 的 SVG 数据拆分），因此 rc.1 用户无需升级 DSH 即可用本版。DSH 0.1.5-alpha.2 用户继续用 **v0.19.0-alpha.1**；0.1.2-rc.1 稳定线继续用 **v0.18.1**。
+
+- 🎯 **适配 DSH 0.1.5-rc.2**：devDependency 钉版、CI 挂载车道与 `SIDEBAR_SERVICE_VERSION` 同步到 rc.2；插件侧**零代码改动**（上游 delta 未触及本插件，逐文件核对见 [docs/plans/2026-09-10-dsh-0.1.5-rc.2-adaptation.md](docs/plans/2026-09-10-dsh-0.1.5-rc.2-adaptation.md)——300 个变更文件里绝大多数只是各包 `package.json` 的版本号单行）。
+- 🎨 **文件图标（#611）与内置 Tab 图标改为彩色**（#531 + #594 合并，实现按 rc.2 重做）：
+  - **文件/文件夹图标走 DSH 官方图形**：回退链末端是宿主 `ui-primitives` 的 `FileTypeIcon`（48 类官方全彩代码/配置图形 + markdown/图片/PDF/Office/视频/文件夹的类目色板），插件**不再自带扩展名表，也不再需要图标懒加载 chunk**——`#429` 那份 563 条彩色数据与 `lib/client-file-icons.js`（255 kB）连同 `fileIconTheme` 设置开关一并删除，彩色就是唯一形态（核心 bundle 因此只增 10 kB）。
+  - **新增对外 `registerFileIcon` API**（能力 `'fileIcons'`）：按扩展名（`exts`）、精确文件名（`names`）、目录名（`folderNames`）注册自己的图标，优先级降序、同级按注册序；**注意**：宿主分类器覆盖任意路径，所以注册 `exts: []` 的 catch-all 会接管所有未具体命中的行。
+  - **内置 tab 图标彩色**：文件 / 文件变动 / 任务管理 / 侧边对话 / 终端 / 浏览器 六个类型与 diff 视图的 glyph 换成彩色版本（颜色全部来自 `--dsw-alias-*` 令牌，皮肤照旧全覆盖）。
+  - **原生右侧栏的 tab 芯片也带图标**：宿主的 tab 定义没有 icon 字段，但 `sidebar.right.pane.tab.title` 槽就是芯片内容——插件在该槽渲染「图标 + 标题」（编辑器 tab 带路径时显示该文件的图标），glyph 为 `aria-hidden`，芯片可访问名不变。
+- 🛠 **CI 修复一：Windows lane 的真实超时**。`ci-windows` 在 2026-09-09/10 窗口内红了 8 次，其中 6 次是真起进程的用例撞上 vitest 默认 5000ms：`tests/agent-pty.spec.ts`（真起 PowerShell + ConPTY）与 `tests/install-powershell.spec.ts`（冷启 `powershell.exe` 实测 12.1s）现在各自声明 30s 预算，且 `vitest.config.ts` 的全局 `testTimeout` 从默认 5000ms 提到 **15s**（第一次真实 Windows 跑又在**第三个**文件上翻车：`tests/git.spec.ts:85` 耗时 9607ms——三个文件同一个根因，逐文件加超时是打地鼠）；`waitForTranscript` 的内层轮询预算从 5000ms 降到 15s，**内层预算必须小于外层**（原先是同一个 5000ms，结构性必然超时）。`ci-windows` 的 `Test` 改跑 `pnpm test:windows`（`--maxWorkers=2`），在 2 核 runner 上不再让真起进程的 spec 互相抢占。
+- 🛠 **CI 修复二：挂载车道的 npm 安装**。`plugin-mount` 的 `npm install -g @deepseek-ai/dsh@<ver>` 曾 4 次失败（2 次 `ETARGET`、2 次 `JavaScript heap out of memory` exit 134）：钉版自身的传递依赖是浮动 `^` 范围，上游**分阶段发布**预发布版时（rc.2 于 09-10 的 14:43–14:57 逐包上线）npm 会组出 rc.1/rc.2 混合 peer 图（3062 条 ERESOLVE）。现在钉一个**已完整发布**的 rc.2（修 ETARGET）并加 `NODE_OPTIONS=--max-old-space-size=4096`（修 OOM）。中途试过 `--legacy-peer-deps`，被真实 CI 否掉：它跳过的正是全局安装必须提供的 peer，`dsh-app-boot` 在 boot 时 require 的 `@deepseek-ai/cordis-plugin-group` 是 peer 而非 dependency，加了它 CLI 直接 `ERR_MODULE_NOT_FOUND`。
+
+### v0.19.0
+
+> 📌 **正式版**（npm `latest`，无 prerelease 后缀）：本版仅支持 **DSH 0.1.5-rc.1+**（peer 下限 `^0.1.5-rc.1`，CI 钉 `@deepseek-ai/dsh@0.1.5-rc.1`）。DSH 0.1.5-alpha.2 用户请继续用 **v0.19.0-alpha.1**（npm `alpha` 标签仍指向它）；0.1.2-rc.1 稳定线继续用 **v0.18.1**。
+
+**✨ 新功能**
+
+- 📝 **新建标签页列表恢复可选说明**（#613）：DSH 0.1.5-rc.1 让 `SidebarRightGuideEntry.description` 回归（可选），插件随之恢复 `TabDescriptor.description`，六个内置类型各写回一条说明（原生指南的 文件 / 文件变动 / 任务管理 / 侧边对话 / 终端 / 浏览器 六行都带上它），`guideDesc*` 词条回到 20 份词典。**宿主的原生指南只在列出的条目 ≤ 4 条时渲染说明**（更长的列表是整列丢弃，不是截断），而插件默认贡献 6 个 guide 条目——因此默认组合下说明不渲染，只有在插件设置页关掉足够多的 tab 类型、把 guide 压到 ≤ 4 条时才会出现。未声明说明的条目仍是「图标 + 标题」单行（插件不补通用兜底句）。
+
+**🐛 修复**
+
+- 无。rc.1 相对 alpha.2 的 delta 很小（373 个变更文件，绝大多数是上游各包版本号、原生右侧栏预览 UI 打磨与测试快照），除上述说明字段回归（并附带上游 `files` 类型改用自己的彩色文件夹图标作指南字形）外，没有需要插件适配的变更。
+
+**🧰 CI 与内部**
+
+- 基线推进到 **DSH 0.1.5-rc.1+**（#613）：peer 下限、devDependency 钉版、CI 挂载车道与 `dsh.plugin.json` 的 `engines.dsh` 同步（rc.1 在 npm 上同时是 `latest` 与 `next`）。
+- 明确未变、不必再核：全局主面板模型（`main` 槽 / `sidebar.panellist` / `ctx.layout` / 根级 `rightbar` + `rightbar.session`，插件仍不接入）、文件地址语法（`packages/util/workspace-path` 只动了版本号）、原生 tab 体宿主契约（`.paneBody` 仍是有确定高度的块级滚动容器）、core / agent / session / subagent 宿主 API 与 `ui-primitives` 导出面（仅 CodeBlock 渲染变化）。
+- `@deepseek-ai/dsh-client-ui-primitives@0.1.5-rc.1` 仍不声明 `dependencies` 而 bundle 仍裸 import `anser` / `shiki` / `@shikijs/langs/*` / `mdast-util-*` / `micromark-*` / `katex`——上一版提升进 devDependencies 的那组包因此保留，不得回退。
+- 真机验证（DSH 0.1.5-rc.1 + 插件 0.19.0）：门禁 `typecheck` / `lint` / `check:consumer-types` 全绿，单测 **124 files · 1296 passed · 9 skipped**，`pnpm peers check` 干净；挂载冒烟对真实 rc.1 **7 passed**（含 tab 体填充断言，以及新增的「指南 ≤4 条时说明才渲染」断言）；本地 3080 实测：guide 六行仍是「图标 + 标题」（6 > 4，说明按上游规则不渲染；上游把胶囊 `min-height` 从 48px 调到 56px），文件树点击 `AGENTS.md` 落到插件编辑器（CodeMirror 就绪），sidechat 输入框贴底（宿主盒 962px == 面板体 962px，composer 底边距 8px），底部工作台与中心列左右边完全重合，`pageerror` 0（控制台仅有第三方 `dsh-tauri-worktree` 的 `/api/dsh-worktree/attach` 500，与本次改动无关）。
 
 ### v0.19.0-alpha.1
 
-> 🧪 **alpha 通道**（npm dist-tag `alpha`，安装 `dsh-better-sidebar@alpha`）：本版仅支持 **DSH 0.1.5-alpha.2+**（peer 下限 `^0.1.5-alpha.2`，CI 钉 `@deepseek-ai/dsh@0.1.5-alpha.2`）。0.1.5-alpha.1 请继续用 **v0.19.0-alpha.0**；0.1.2-rc.1 稳定线用 **v0.18.1**（npm `latest`）。
+> 🧪 **alpha 通道**（npm dist-tag `alpha`，安装 `dsh-apes-sidebar@alpha`）：本版仅支持 **DSH 0.1.5-alpha.2+**（peer 下限 `^0.1.5-alpha.2`，CI 钉 `@deepseek-ai/dsh@0.1.5-alpha.2`）。0.1.5-alpha.1 请继续用 **v0.19.0-alpha.0**；0.1.2-rc.1 稳定线用 **v0.18.1**（npm `latest`）。
 
 **✨ 新功能**
 
@@ -282,7 +332,7 @@ GitHub topic [`dsh-better-sidebar`](https://github.com/topics/dsh-better-sidebar
 
 ### v0.19.0-alpha.0
 
-> 🧪 **alpha 通道**（npm dist-tag `alpha`，安装 `dsh-better-sidebar@alpha`）：本版仅支持 **DSH 0.1.5-alpha.1+**（peer 下限 `^0.1.5-alpha.1`，CI 钉 `@deepseek-ai/dsh@0.1.5-alpha.1`）。0.1.2-rc.1 稳定线请继续用 **v0.18.1**（npm `latest`）。
+> 🧪 **alpha 通道**（npm dist-tag `alpha`，安装 `dsh-apes-sidebar@alpha`）：本版仅支持 **DSH 0.1.5-alpha.1+**（peer 下限 `^0.1.5-alpha.1`，CI 钉 `@deepseek-ai/dsh@0.1.5-alpha.1`）。0.1.2-rc.1 稳定线请继续用 **v0.18.1**（npm `latest`）。
 
 **✨ 新功能**
 
@@ -298,6 +348,11 @@ GitHub topic [`dsh-better-sidebar`](https://github.com/topics/dsh-better-sidebar
 
 - 真机挂载冒烟门禁钉 0.1.5-alpha.1，e2e 增加「展开原生栏 → 经引导页逐个打开插件 tab 类型」的巡检；typecheck / lint / 单测 / 挂载车道全绿。
 
+### v0.19.0（未发布）
+
+- 🎨 **可选彩色图标主题**：设置页「文件 → 文件图标」可在**内置单色**与**彩色品牌图标**之间切换——彩色主题含 563 条规则（218 扩展名 + 197 精确文件名 + 148 目录名，如 `.tsx → React`、`package.json → npm`、`node_modules` 着色），数据在**懒加载 chunk**（`lib/client-file-icons.js`）里，只有选中时才下载，默认关闭时启动零开销。数据源自 [#429](https://github.com/omdsh-dev/DSH-better-sidebar/pull/429)（@fenter）。
+- 🎨 **文件图标多样化 + 对外图标注册 API（[file-icons.tsx](./src/client/file-icons.tsx)）**：文件树与编辑器文件 tab 不再是单一 `VscFile`——markdown / 图片媒体 / PDF / JSON / 40+ 代码扩展 / 配置 / 数据库 / lock / 压缩包各有专属 glyph（VSCodicons 单色 `currentColor`，遵循皮肤契约），未知扩展回退通用图标。`ctx.betterSidebar` 新增 `registerFileIcon`（`features` 含 `'fileIcons'`）：按扩展名 / 精确文件名（`names`）/ 目录名（`folderNames`）注册自定义图标（彩色 ReactNode 亦可，颜色责任在注册方），`exts: []` 为全局默认（只兜内置 glyph 没认领的扩展，不吞掉内置多样性），保留扩展名 `'folder'` / `'folder-open'` 可换目录行图标；`fileIcon` / `folderIcon` 为权威解析器（完整回退链 + 逐工厂崩溃隔离），注册/注销即时生效。接入示例见[外部插件指南 §7](./docs/external-plugin-guide.md)。
+
 ### v0.18.1
 
 > 📌 **正式版**（npm `latest`）：DSH 基线不变（**0.1.2-rc.1+**，peer 下限 `^0.1.2-rc.1`）——本版是 v0.18.0 之后的增量发布：变更面板预览能力增强、文件树可写，以及五项修复。
@@ -321,7 +376,7 @@ GitHub topic [`dsh-better-sidebar`](https://github.com/topics/dsh-better-sidebar
 
 ### v0.18.0
 
-> 📌 **正式版**（npm `latest`）：本版仅支持 **DSH 0.1.2-rc.1+**（peer 下限 `^0.1.2-rc.1`）；不再支持 0.1.0-rc.8 ~ 0.1.1-rc.2——DSH stable 用户请固定安装 `dsh-better-sidebar@0.17.1`，停留在 0.1.2-alpha.x 的宿主继续用 `dsh-better-sidebar@alpha`（v0.18.0-alpha.0）。
+> 📌 **正式版**（npm `latest`）：本版仅支持 **DSH 0.1.2-rc.1+**（peer 下限 `^0.1.2-rc.1`）；不再支持 0.1.0-rc.8 ~ 0.1.1-rc.2——DSH stable 用户请固定安装 `dsh-apes-sidebar@0.17.1`，停留在 0.1.2-alpha.x 的宿主继续用 `dsh-apes-sidebar@alpha`（v0.18.0-alpha.0）。
 
 **✨ 新功能**
 
@@ -346,7 +401,7 @@ GitHub topic [`dsh-better-sidebar`](https://github.com/topics/dsh-better-sidebar
 
 **🌐 生态收录**
 
-- 新收录 10+ 插件：dsh-better-sidebar-icons（#441）、dsh-sidenote（#451，原 dsh-sidechat #470）、dsh-github-workbench（#410）、dsh-bilingual-reader（#379）、dsh-server-deck（#413）、dsh-md-export（#405）、dsh-code-nav（#404）、dsh-suhuang-scroll（#392）、dsh-better-overleaf（#370）等（均含 18+ 语言 i18n 补齐）
+- 新收录 10+ 插件：dsh-apes-sidebar-icons（#441）、dsh-sidenote（#451，原 dsh-sidechat #470）、dsh-github-workbench（#410）、dsh-bilingual-reader（#379）、dsh-server-deck（#413）、dsh-md-export（#405）、dsh-code-nav（#404）、dsh-suhuang-scroll（#392）、dsh-better-overleaf（#370）等（均含 18+ 语言 i18n 补齐）
 
 <details>
 <summary><b>历史版本（v0.12.0 – v0.15.2）</b></summary>
@@ -359,13 +414,13 @@ GitHub topic [`dsh-better-sidebar`](https://github.com/topics/dsh-better-sidebar
 
 ### v0.18.1-alpha.0
 
-> 🧪 **alpha 通道**：本版仅支持 **DSH 0.1.2-alpha.x**（peer 下限 `^0.1.2-alpha.3`，npm dist-tag `alpha`，安装 `dsh-better-sidebar@alpha`）。该版本号未单独发布，内容已并入 **v0.18.0** 正式版。
+> 🧪 **alpha 通道**：本版仅支持 **DSH 0.1.2-alpha.x**（peer 下限 `^0.1.2-alpha.3`，npm dist-tag `alpha`，安装 `dsh-apes-sidebar@alpha`）。该版本号未单独发布，内容已并入 **v0.18.0** 正式版。
 
 - 🔗 **适配 DSH 0.1.2-alpha.3（npm 已发布，`alpha` dist-tag）**：CI 挂载门禁钉版、`dsh.plugin.json` engines 下限与 `@deepseek-ai/*` peer / devDependencies 基线升至 0.1.2-alpha.3（真机挂载冒烟 14/14 验证）。逐点核查了 alpha.2 → alpha.3 全部 117 个 commit：插件依赖的宿主契约（token 鉴权、斜杠 RPC、`MarkdownText` labels、`sidechat.events` 所依赖的事件流与持久化 API、`SettingsNamespaceInput`、`SUBAGENT_DESCRIPTOR_VERSION`（仍为 3）、`dsh-client-store`、profile 加载器、node-pty 钉版）均无变化，无需代码适配；alpha.3 的破坏性改动（`BeginSubmissionInput.mode` 必填、subagent 错误码改名 `attachment-invalid`、SQLite 持久化后端移除、投影 change feed 收紧为 identity-gated）经核实均不触及本插件。
 
 ### v0.18.0-alpha.0
 
-> 🧪 **alpha 通道**：本版仅支持 **DSH 0.1.2-alpha.x**（peer 下限 `^0.1.2-alpha.2`，npm dist-tag `alpha`，安装 `dsh-better-sidebar@alpha`）；不再支持 0.1.0-rc.8 ~ 0.1.1-rc.2——stable DSH 用户请用 v0.17.1（npm `latest`）。
+> 🧪 **alpha 通道**：本版仅支持 **DSH 0.1.2-alpha.x**（peer 下限 `^0.1.2-alpha.2`，npm dist-tag `alpha`，安装 `dsh-apes-sidebar@alpha`）；不再支持 0.1.0-rc.8 ~ 0.1.1-rc.2——stable DSH 用户请用 v0.17.1（npm `latest`）。
 
 - 🔗 **适配 DSH 0.1.2-alpha.2（npm 已发布，`alpha` dist-tag）**：CI 挂载门禁钉版与 `@deepseek-ai/*` devDependencies 基线升至 0.1.2-alpha.2（真机挂载冒烟 14/14 验证）。适配点：`dsh-settings` 移除运行时导出 `settingsNamespace`（命名空间改为编译期校验，宿主侧直接传常量）；`dsh-subagent` 描述符版本 2→3（由宿主包盖章，测试断言跟随 `SUBAGENT_DESCRIPTOR_VERSION` 常量）；`SessionEvent.ignorable` 恢复与 Remote 网关 `RemoteError` 封装经核实对本插件无破坏。
 - 🐛 **修复 DSH 0.1.2-alpha.1+ 上侧边对话转录空白**：转录轮询此前仍走 alpha.1 已移除的 `ctx.connection.api`（错误被静默吞掉，tab 永远渲染空转录），现改由插件自有 `sidechat.events` 路由供给（活线程读内存事件日志、冷线程读会话持久化，`afterSeq` 增量拉取，[sidechat-routes.ts](./src/sidechat-routes.ts)）。
@@ -403,7 +458,7 @@ GitHub topic [`dsh-better-sidebar`](https://github.com/topics/dsh-better-sidebar
 **🐛 修复**
 
 - 🛒 **DSH 市场受管安装兼容**（[#338](https://github.com/omdsh-dev/DSH-better-sidebar/pull/338)）：移除 `peerDependencies` 里的公开版 `cordis`（市场预览硬拒依赖字段出现 `cordis`，optional 无效）——npm 包满足 [dsh-community-market 安装规范](https://github.com/anywhere-labs/deepseek-harness-desktop/blob/master/dsh-community-market/docs/install-and-uninstall.zh.md)，dshfind / 1024Store 目录里的条目重新获得 `repository_backlink` 验证目标，可直接从 Desktop 市场受管安装
-- 🔤 **类型基底迁移到 `@deepseek-ai/cordis`**（[#338](https://github.com/omdsh-dev/DSH-better-sidebar/pull/338)）：`Context` = 真实 vendored cordis Context 与结构化服务面的**交集**，`ctx.betterSidebar` 类型合并改挂 `@deepseek-ai/cordis`，公开版 cordis 不再被依赖。**消费者迁移**：`import type { Context } from 'cordis'` 改为 `import type { Context } from '@deepseek-ai/cordis'`（`import type {} from 'dsh-better-sidebar'` 的类型合并方式不变）；未使用该导入的插件无影响
+- 🔤 **类型基底迁移到 `@deepseek-ai/cordis`**（[#338](https://github.com/omdsh-dev/DSH-better-sidebar/pull/338)）：`Context` = 真实 vendored cordis Context 与结构化服务面的**交集**，`ctx.betterSidebar` 类型合并改挂 `@deepseek-ai/cordis`，公开版 cordis 不再被依赖。**消费者迁移**：`import type { Context } from 'cordis'` 改为 `import type { Context } from '@deepseek-ai/cordis'`（`import type {} from 'dsh-apes-sidebar'` 的类型合并方式不变）；未使用该导入的插件无影响
 - 🧩 **插件树内 `ctx.betterSidebar` 读取全面修复**（[#357](https://github.com/omdsh-dev/DSH-better-sidebar/pull/357)，修复 [#356](https://github.com/omdsh-dev/DSH-better-sidebar/issues/356)）：npm 安装的 DSH 0.1.1-rc.x（web bundle）下侧边栏页面每次加载即崩（`cannot get property "betterSidebar" without inject`）——26 处内部直读 `ctx.betterSidebar` 改走 `ctx.get('betterSidebar')`（root reflect store 解析，不受 fiber 链影响）；外部消费者 `inject: ['betterSidebar'] + ctx.betterSidebar` 契约不变
 - 🔐 **文件 API 会话工作区边界**（[#345](https://github.com/omdsh-dev/DSH-better-sidebar/pull/345)，修复 [#328](https://github.com/omdsh-dev/DSH-better-sidebar/issues/328)）：`fs.tree / fs.read / fs.write` 的 workspace 越界访问修复；媒体、HTML 预览与上传统一 real-path 符号链接校验；新增绝对路径 / 符号链接 / 上传 / 嵌套 Git 会话回归测试
 - 🪟 **面板宿主层级与视口裁剪**（[#330](https://github.com/omdsh-dev/DSH-better-sidebar/pull/330) [#278](https://github.com/omdsh-dev/DSH-better-sidebar/pull/278)，修复 [#277](https://github.com/omdsh-dev/DSH-better-sidebar/issues/277)）：面板宿主层 z-index 40→25——低于 DSH cordis 动态插件面板 30，工作台不再遮挡 cordis 清单 / 审批面（AppFrame 20 之上、100+ 浮层之下）；宿主 `overflow: hidden` 裁剪视口边缘，收起的面板不再把文档撑出双向滚动（实测 `scrollWidth` 2289→1672 / `scrollHeight` 1280→1032，任意皮肤）
@@ -559,15 +614,15 @@ GitHub topic [`dsh-better-sidebar`](https://github.com/topics/dsh-better-sidebar
 
 ## 🔌 服务化扩展
 
-从 v0.4.0 起暴露 `ctx.betterSidebar` 服务，其他插件可注册侧边栏页面与文件预览器（内置 8 tab + 6 viewer 亦通过同一服务注册）。v0.12.1 补齐基座能力（完整类型导出、能力探测、状态订阅、tab 角标、生命周期回调、定向打开、插件自有设置等）。
+从 v0.4.0 起暴露 `ctx.betterSidebar` 服务，其他插件可注册侧边栏页面与文件预览器（内置 8 tab + 6 viewer 亦通过同一服务注册）。v0.12.1 补齐基座能力（完整类型导出、能力探测、状态订阅、tab 角标、生命周期回调、定向打开、插件自有设置等）。v0.19.0 起新增文件图标注册：`registerFileIcon` 按扩展名（或保留的 `'folder'` / `'folder-open'` 目录扩展名、`exts: []` 全局默认）替换文件树与文件 tab 的图标，彩色 ReactNode 亦可——内置消费、注册即生效，无需自己接线。
 
 完整接入文档（全字段、匹配算法、HMR 陷阱、声明式设置、版本探测、原生栏承载面与皮肤契约）：**[`docs/external-plugin-guide.md`](./docs/external-plugin-guide.md)**；仓库开发规则（硬约束 / CI / 发版）见 [`AGENTS.md`](./AGENTS.md)。
 
 ### ➕ 添加插件（推荐插件目录）
 
-设置页「侧边卡片」两个网格末尾的**虚线卡片**分别打开 Tab / 预览插件弹窗：声明扩展点、「**在 GitHub 上浏览更多插件**」按钮（[GitHub topic `dsh-better-sidebar`](https://github.com/topics/dsh-better-sidebar)）、推荐插件目录（名字 / 仓库 / 简介 / 安装脚本），每个条目「**跳转**」直达仓库、「**复制**」把安装命令写入剪贴板。
+设置页「侧边卡片」两个网格末尾的**虚线卡片**分别打开 Tab / 预览插件弹窗：声明扩展点、「**在 GitHub 上浏览更多插件**」按钮（[GitHub topic `dsh-apes-sidebar`](https://github.com/topics/dsh-apes-sidebar)）、推荐插件目录（名字 / 仓库 / 简介 / 安装脚本），每个条目「**跳转**」直达仓库、「**复制**」把安装命令写入剪贴板。
 
-**收录新插件**：向 [`src/client/plugins-tabs.ts`](./src/client/plugins-tabs.ts)（Tab 注册）或 [`src/client/plugins-viewers.ts`](./src/client/plugins-viewers.ts)（文件预览注册）追加一条 `PluginEntry`，并把仓库打上 `dsh-better-sidebar` topic；数据完整性由 `tests/plugin-list.spec.ts` 守护。
+**收录新插件**：向 [`src/client/plugins-tabs.ts`](./src/client/plugins-tabs.ts)（Tab 注册）或 [`src/client/plugins-viewers.ts`](./src/client/plugins-viewers.ts)（文件预览注册）追加一条 `PluginEntry`，并把仓库打上 `dsh-apes-sidebar` topic；数据完整性由 `tests/plugin-list.spec.ts` 守护。
 
 ## 🛠️ 开发与构建
 
@@ -614,7 +669,7 @@ Windows / Linux / macOS 三平台适配（macOS 日常验证；其余经单元
 ## 🤝 参与贡献
 
 - **代码改动走 PR**：`feat/*` / `fix/*` 分支开发 → `gh pr create`；纯文档改动可直接推 main
-- **收录生态插件**：给仓库打 `dsh-better-sidebar` topic + 向 [`src/client/plugins-tabs.ts`](./src/client/plugins-tabs.ts) / [`plugins-viewers.ts`](./src/client/plugins-viewers.ts) 提 PR
+- **收录生态插件**：给仓库打 `dsh-apes-sidebar` topic + 向 [`src/client/plugins-tabs.ts`](./src/client/plugins-tabs.ts) / [`plugins-viewers.ts`](./src/client/plugins-viewers.ts) 提 PR
 - **提交前自检**：`pnpm typecheck && pnpm build && pnpm test`（或 `make check` 一键聚合；CI 另有 npm 打包 → 真实挂载 → 无头渲染门禁 `pnpm test:mount`，及聚合双挂载回归 `pnpm test:mount:aggregate`）
 - 仓库工作规范见 [`AGENTS.md`](./AGENTS.md)（含仓库硬约束与 CI 说明）
 
@@ -645,5 +700,5 @@ Windows / Linux / macOS 三平台适配（macOS 日常验证；其余经单元
 ---
 
 <div align="center">
-  <sub>MIT License · Built for the <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a> ecosystem · 在 <a href="https://github.com/topics/dsh-better-sidebar">topic dsh-better-sidebar</a> 发现更多生态插件</sub>
+  <sub>MIT License · Built for the <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a> ecosystem · 在 <a href="https://github.com/topics/dsh-apes-sidebar">topic dsh-apes-sidebar</a> 发现更多生态插件</sub>
 </div>

README_EN.md

@@ -1,16 +1,19 @@
-# dsh-better-sidebar
+# dsh-apes-sidebar
+
+> [!IMPORTANT]
+> **Built on DSH's native sidebar API** (since v0.19.0, DSH `0.1.5-rc.1+`): the right column *is* DSH's own sidebar — every plugin tab type and tab body registers and opens through `ctx.sidebarRightTabs` / `ctx.sidebarRight`, every file open from the chat goes through `ctx.sidebarRight.openResource('dsh-resource://file/…')`, and the plugin **no longer draws a right panel of its own** (the old free-window capability is gone with it). The self-drawn bottom workbench and the `ctx.betterSidebar` service other plugins register against are unchanged — see the [plugin integration guide](docs/external-plugin-guide.md).
 
 <!-- Hero -->
 <div align="center">
   <b style="font-size: 1.15em;">A service-oriented sidebar framework, and a complete workbench out of the box</b><br /><br />
-  <a href="https://www.npmjs.com/package/dsh-better-sidebar"><img alt="npm version" src="https://img.shields.io/npm/v/dsh-better-sidebar" /></a>
-  <a href="https://www.npmjs.com/package/dsh-better-sidebar"><img alt="npm downloads" src="https://img.shields.io/npm/dm/dsh-better-sidebar" /></a>
+  <a href="https://www.npmjs.com/package/dsh-apes-sidebar"><img alt="npm version" src="https://img.shields.io/npm/v/dsh-apes-sidebar" /></a>
+  <a href="https://www.npmjs.com/package/dsh-apes-sidebar"><img alt="npm downloads" src="https://img.shields.io/npm/dm/dsh-apes-sidebar" /></a>
   <a href="https://github.com/omdsh-dev/DSH-better-sidebar/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/omdsh-dev/DSH-better-sidebar/actions/workflows/ci.yml/badge.svg" /></a>
   <a href="https://github.com/omdsh-dev/DSH-better-sidebar/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/omdsh-dev/DSH-better-sidebar" /></a>
   <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg" /></a>
   <a href="https://dshfind.com/en/plugins/omdsh-dev/DSH-better-sidebar?ref=badge"><img alt="dshfind" src="https://dshfind.com/api/badge/omdsh-dev/DSH-better-sidebar?lang=en" /></a><br /><br />
-  <a href="https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions"><img alt="Supported DSH versions (v0.18.1): 0.1.2-rc.1+" src="https://img.shields.io/badge/DSH-0.1.2--rc.1%2B-4d6bfe" /></a>
-  <a href="https://github.com/topics/dsh-better-sidebar"><img alt="Plugin ecosystem: GitHub topic dsh-better-sidebar" src="https://img.shields.io/badge/plugin%20ecosystem-topic%20dsh--better--sidebar-4d6bfe" /></a><br /><br />
+  <a href="https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions"><img alt="Supported DSH versions (v0.19.1): 0.1.5-rc.1+ (verified on rc.2)" src="https://img.shields.io/badge/DSH-0.1.5--rc.1%2B_%28verified_rc.2%29-4d6bfe" /></a>
+  <a href="https://github.com/topics/dsh-apes-sidebar"><img alt="Plugin ecosystem: GitHub topic dsh-apes-sidebar" src="https://img.shields.io/badge/plugin%20ecosystem-topic%20dsh--better--sidebar-4d6bfe" /></a><br /><br />
   <img alt="File management" src="https://img.shields.io/badge/-File%20management-4d6bfe" /> <img alt="Edit &amp; preview" src="https://img.shields.io/badge/-Edit%20%26%20preview-4d6bfe" /> <img alt="Embedded browser" src="https://img.shields.io/badge/-Embedded%20browser-4d6bfe" /> <img alt="Real terminal" src="https://img.shields.io/badge/-Real%20terminal-4d6bfe" /> <img alt="Changes" src="https://img.shields.io/badge/-Changes-4d6bfe" /> <img alt="Background tasks" src="https://img.shields.io/badge/-Background%20tasks-4d6bfe" /> <img alt="Side Chat" src="https://img.shields.io/badge/-Side%20Chat-4d6bfe" /> <img alt="Plugin integration" src="https://img.shields.io/badge/-Plugin%20integration-4d6bfe" /><br /><br />
   <b>A dual workbench (right sidebar + bottom panel)</b> that opens its <code>ctx.betterSidebar</code> service to every plugin —<br />
   register new sidebar pages and file viewers via <code>registerTab</code> / <code>registerFileViewer</code>.
@@ -22,7 +25,7 @@
 
 <div align="center">
   <video src="https://github.com/user-attachments/assets/23187822-047e-45cc-b480-fe997bd55b86" muted autoplay loop playsinline controls width="100%"></video>
-  <img alt="dsh-better-sidebar workbench" src="https://github.com/user-attachments/assets/dfdb875e-a1a8-4d4b-8340-353736b1708f" />
+  <img alt="dsh-apes-sidebar workbench" src="https://github.com/user-attachments/assets/dfdb875e-a1a8-4d4b-8340-353736b1708f" />
 </div>
 
 ## 📑 Contents
@@ -61,14 +64,14 @@
 **Prerequisites**: DSH installed (`dsh web` boots), Node.js ≥ 20, pnpm ≥ 10.
 
 **Supported DSH versions**:
-<a href="https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions"><img alt="Supported DSH versions (v0.18.1): 0.1.2-rc.1+" src="https://img.shields.io/badge/DSH-0.1.2--rc.1%2B-4d6bfe" /></a>
+<a href="https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions"><img alt="Supported DSH versions (v0.19.1): 0.1.5-rc.1+ (verified on rc.2)" src="https://img.shields.io/badge/DSH-0.1.5--rc.1%2B_%28verified_rc.2%29-4d6bfe" /></a>
 
-> 📌 **Stable release**: starting with `v0.18.0` the plugin targets DSH **0.1.2-rc.1+** (npm dist-tag `latest`) and drops 0.1.0-rc.8 ~ 0.1.1-rc.2 — stable-DSH (≤ 0.1.1-rc.2) users should stay pinned to `dsh-better-sidebar@0.17.1` (`@latest` now points at v0.18.0); hosts still on 0.1.2-alpha.x should upgrade DSH first, or keep `dsh-better-sidebar@alpha` (v0.18.0-alpha.0).
+> 📌 **Stable release**: starting with `v0.19.0` the plugin targets DSH **0.1.5-rc.1+** (npm dist-tag `latest`; `v0.19.1` is verified end-to-end against **0.1.5-rc.2**, so rc.1 hosts need no DSH upgrade — the peer floor stays `^0.1.5-rc.1`). Hosts still on DSH 0.1.5-alpha.2 should stay pinned to `dsh-apes-sidebar@0.19.0-alpha.1`; the 0.1.2-rc.1 stable line keeps using `dsh-apes-sidebar@0.18.x`; DSH ≤ 0.1.1-rc.2 should use `dsh-apes-sidebar@0.17.1`.
 
 ```sh
-dsh plugin --profile web add dsh-better-sidebar@latest   # first run fails: pnpm 11 blocks node-pty build scripts (the dependency is still written)
+dsh plugin --profile web add dsh-apes-sidebar@latest   # first run fails: pnpm 11 blocks node-pty build scripts (the dependency is still written)
 cd ~/.dsh/profiles/web && pnpm approve-builds --all      # allow the build scripts (re-runs the install automatically)
-dsh plugin --profile web add dsh-better-sidebar@latest   # re-run succeeds
+dsh plugin --profile web add dsh-apes-sidebar@latest   # re-run succeeds
 ```
 
 Then **hard-refresh the browser** (Cmd/Ctrl+Shift+R) to see the sidebar (DSH hot-reloads client changes; only host-half updates need a restart).
@@ -76,10 +79,10 @@ Then **hard-refresh the browser** (Cmd/Ctrl+Shift+R) to see the sidebar (DSH hot
 **Or let DSH install it for you** — paste this prompt into any DSH session:
 
 ```text
-Install the dsh-better-sidebar plugin (a sidebar workbench for DSH):
-1. Run: dsh plugin --profile web add dsh-better-sidebar@latest (the first run fails because pnpm 11 blocks node-pty build scripts — that's expected)
+Install the dsh-apes-sidebar plugin (a sidebar workbench for DSH):
+1. Run: dsh plugin --profile web add dsh-apes-sidebar@latest (the first run fails because pnpm 11 blocks node-pty build scripts — that's expected)
 2. In ~/.dsh/profiles/web run: pnpm approve-builds --all (allows the build scripts and re-runs the install)
-3. Run the add command again: dsh plugin --profile web add dsh-better-sidebar@latest
+3. Run the add command again: dsh plugin --profile web add dsh-apes-sidebar@latest
 4. When done, remind me to hard-refresh the browser (Cmd/Ctrl+Shift+R)
 If anything fails, check the troubleshooting table in the README at https://github.com/omdsh-dev/DSH-better-sidebar
 ```
@@ -90,7 +93,7 @@ If anything fails, check the troubleshooting table in the README at https://gith
 <summary><b>Updating</b></summary>
 
 ```sh
-dsh plugin --profile web add dsh-better-sidebar@latest
+dsh plugin --profile web add dsh-apes-sidebar@latest
 ```
 
 or bump the version in `~/.dsh/profiles/web/package.json` (e.g. `"^0.16.1"`) and run `pnpm install`. Then hard-refresh the browser (Cmd/Ctrl+Shift+R) — client changes do not need a DSH restart.
@@ -105,10 +108,10 @@ or bump the version in `~/.dsh/profiles/web/package.json` (e.g. `"^0.16.1"`) and
 | `Ignored build scripts` | pnpm 11 blocked build scripts. Run `pnpm approve-builds --all` in the profile directory (`~/.dsh/profiles/web`). |
 | `minimum release age` / version `< 24h` | The release is younger than 24 hours. Wait, or re-run once (pnpm auto-adds `minimumReleaseAgeExclude`). |
 | "profile directory not found" | Run `dsh web` once so it initializes `~/.dsh/profiles/web`. |
-| Two sidebars on the page | Double-mount. Old hand-written line: `~/.dsh/profiles/web/cordis.patch.yml` still has `- insert: ... better-sidebar ...` — delete it (a same-id duplicate mount makes the loader fail loudly with `duplicate loader entry id`). When an aggregate bundle (e.g. `@linxin666/dsh-web-ui-all`) mounts this package under a **different** id, the plugin's own bundle patch backs off automatically since 0.13.x (it detects an already-enabled mount of the same package name and does not mount itself) — no manual fix needed; if it still double-mounts, make sure the aggregate bundle precedes `dsh-better-sidebar` in `dsh.profile.bundles`. |
+| Two sidebars on the page | Double-mount. Old hand-written line: `~/.dsh/profiles/web/cordis.patch.yml` still has `- insert: ... better-sidebar ...` — delete it (a same-id duplicate mount makes the loader fail loudly with `duplicate loader entry id`). When an aggregate bundle (e.g. `@linxin666/dsh-web-ui-all`) mounts this package under a **different** id, the plugin's own bundle patch backs off automatically since 0.13.x (it detects an already-enabled mount of the same package name and does not mount itself) — no manual fix needed; if it still double-mounts, make sure the aggregate bundle precedes `dsh-apes-sidebar` in `dsh.profile.bundles`. |
 | Terminal fails on Windows | `node-pty` relies on prebuilt binaries; if none match your Node version, install a build toolchain (VS Build Tools). Mainstream Node versions are usually covered. |
 | Terminal shows "node-pty failed to load" | The `node-pty` install is missing or broken (e.g. pnpm skipped its build script). The terminal banner shows a repair command — copy it into a terminal/cmd on the DSH machine and run it (in `~/.dsh/profiles/web`: `pnpm approve-builds --all && pnpm rebuild node-pty`), then restart DSH and click Retry. The plugin and DSH core share the same `node-pty@^1.1.0`, so the repair restores both. |
-| `dsh: command not found` | Install DSH first, or run `npx -y --package @deepseek-ai/dsh dsh plugin --profile web add dsh-better-sidebar@latest`. |
+| `dsh: command not found` | Install DSH first, or run `npx -y --package @deepseek-ai/dsh dsh plugin --profile web add dsh-apes-sidebar@latest`. |
 
 </details>
 
@@ -120,11 +123,11 @@ To debug local changes or track the dev branch, point the dependency at a local
 ```text
 1. git clone https://github.com/omdsh-dev/DSH-better-sidebar.git ~/Code/DSH-better-sidebar
    cd ~/Code/DSH-better-sidebar && pnpm install && pnpm build
-2. In ~/.dsh/profiles/web/package.json dependencies write "dsh-better-sidebar": "link:<absolute path of the clone>"
+2. In ~/.dsh/profiles/web/package.json dependencies write "dsh-apes-sidebar": "link:<absolute path of the clone>"
 3. Append this mount line to ~/.dsh/profiles/web/cordis.patch.yml (to pick the terminal shell, add `config.shell`; `config.shellArgs` starts it with explicit args — when non-empty they replace the default `-l`. When omitted the host resolves `$SHELL` / the login shell / powershell.exe):
    - insert:
        - id: better-sidebar
-         name: 'dsh-better-sidebar'
+         name: 'dsh-apes-sidebar'
          config:
            shell: /bin/zsh
            shellArgs:
@@ -134,7 +137,7 @@ To debug local changes or track the dev branch, point the dependency at a local
 5. Restart DSH and hard-refresh
 ```
 
-Update: `git pull && pnpm install && pnpm build` → just hard-refresh the browser (client changes hot-reload; only host-half changes need a DSH restart). To switch back to the npm channel, restore `"dsh-better-sidebar": "^0.16.1"` and re-run `pnpm install`.
+Update: `git pull && pnpm install && pnpm build` → just hard-refresh the browser (client changes hot-reload; only host-half changes need a DSH restart). To switch back to the npm channel, restore `"dsh-apes-sidebar": "^0.16.1"` and re-run `pnpm install`.
 
 </details>
 
@@ -148,7 +151,7 @@ git clone https://github.com/omdsh-dev/DSH-better-sidebar.git && cd DSH-better-s
 pnpm install && pnpm build
 node scripts/package-registry.mjs   # assemble the registry/ staging (manifest + artifacts + README, not committed)
 dsh registry install ./registry     # install (disabled by default)
-dsh registry enable dsh-external/dsh-better-sidebar
+dsh registry enable dsh-external/dsh-apes-sidebar
 ```
 
 Update: `git pull && pnpm install && pnpm build` → `node scripts/package-registry.mjs` → `dsh registry uninstall/install/enable`. Remove the other channel's mount before switching.
@@ -173,7 +176,7 @@ Update: `git pull && pnpm install && pnpm build` → `node scripts/package-regis
 The `ctx.betterSidebar` service opens two extension points to every plugin: **`registerTab` (sidebar pages)** and **`registerFileViewer` (file previewers)**. The 8 built-in tabs + 6 viewers register through the exact same API — fully equal capabilities.
 
 ```ts
-import type {} from 'dsh-better-sidebar'  // triggers the ctx.betterSidebar type merge
+import type {} from 'dsh-apes-sidebar'  // triggers the ctx.betterSidebar type merge
 export const inject = ['betterSidebar']
 export function apply(ctx: Context) {
   ctx.effect(() => ctx.betterSidebar.registerTab({
@@ -187,7 +190,7 @@ export function apply(ctx: Context) {
 }
 ```
 
-The GitHub topic [`dsh-better-sidebar`](https://github.com/topics/dsh-better-sidebar) already hosts **28+ ecosystem plugins** (and growing):
+The GitHub topic [`dsh-apes-sidebar`](https://github.com/topics/dsh-apes-sidebar) already hosts **28+ ecosystem plugins** (and growing):
 
 <div align="center">
   <a href="https://github.com/user-attachments/assets/d4385b7e-aab4-425d-a5c4-2da5da81a34e"><img width="66%" alt="The built-in Add Plugins modal: recommended catalog + one-click install command" src="https://github.com/user-attachments/assets/d4385b7e-aab4-425d-a5c4-2da5da81a34e" /></a><br />
@@ -210,7 +213,7 @@ The GitHub topic [`dsh-better-sidebar`](https://github.com/topics/dsh-better-sid
 | [GULI-lab/DSH-element-source](https://github.com/GULI-lab/DSH-element-source) | <img alt="stars" src="https://img.shields.io/github/stars/GULI-lab/DSH-element-source?style=flat&color=4d6bfe" /> | Click any UI element on your dev page to jump to its Vue / React / Svelte / Angular source, straight into the chat |
 | [Lzh3070/dsh-file-review-tab](https://github.com/Lzh3070/dsh-file-review-tab) | <img alt="stars" src="https://img.shields.io/github/stars/Lzh3070/dsh-file-review-tab?style=flat&color=4d6bfe" /> | File-change review tab: line-level red/green diffs + undo + chat-line deep links |
 | [yq04/dsh-git-remotes](https://github.com/yq04/dsh-git-remotes) | <img alt="stars" src="https://img.shields.io/github/stars/yq04/dsh-git-remotes?style=flat&color=4d6bfe" /> | Git remotes tab: branches / upstream / ahead-behind, fetch with prune, ff-only pull, confirm-before-push |
-| [ztyhehe/dsh-better-sidebar-svn](https://github.com/ztyhehe/dsh-better-sidebar-svn) | <img alt="stars" src="https://img.shields.io/github/stars/ztyhehe/dsh-better-sidebar-svn?style=flat&color=4d6bfe" /> | SVN source-control tab: status / diff / log / commit / update / revert / conflict resolution — symmetric to the built-in Git panel |
+| [ztyhehe/dsh-apes-sidebar-svn](https://github.com/ztyhehe/dsh-apes-sidebar-svn) | <img alt="stars" src="https://img.shields.io/github/stars/ztyhehe/dsh-apes-sidebar-svn?style=flat&color=4d6bfe" /> | SVN source-control tab: status / diff / log / commit / update / revert / conflict resolution — symmetric to the built-in Git panel |
 | [Melody-max114/dsh-excel-panel](https://github.com/Melody-max114/dsh-excel-panel) | <img alt="stars" src="https://img.shields.io/github/stars/Melody-max114/dsh-excel-panel?style=flat&color=4d6bfe" /> | Excel editing: xlsx preview/edit, live formula evaluation, merged cells, save back to the original file |
 | [v587d/dsh-anysearch-refs](https://github.com/v587d/dsh-anysearch-refs) | <img alt="stars" src="https://img.shields.io/github/stars/v587d/dsh-anysearch-refs?style=flat&color=4d6bfe" /> | AnySearch results as sidebar cards: query, source snippets, highlighted keywords |
 | [mlosun/dsh-docs-panel](https://github.com/mlosun/dsh-docs-panel) | <img alt="stars" src="https://img.shields.io/github/stars/mlosun/dsh-docs-panel?style=flat&color=4d6bfe" /> | Global docs panel: portable Markdown notes, readable from any workspace |
@@ -223,7 +226,7 @@ The GitHub topic [`dsh-better-sidebar`](https://github.com/topics/dsh-better-sid
 | [yq04/dsh-turn-review](https://github.com/yq04/dsh-turn-review) | <img alt="stars" src="https://img.shields.io/github/stars/yq04/dsh-turn-review?style=flat&color=4d6bfe" /> | Turn review: review agent changes turn by turn |
 | [Ghz114514/dsh-refpics](https://github.com/Ghz114514/dsh-refpics) | <img alt="stars" src="https://img.shields.io/github/stars/Ghz114514/dsh-refpics?style=flat&color=4d6bfe" /> | Pinterest-style reference-image search: masonry wall, sidebar board, downloads, save-to-Eagle |
 | [yzlin499/dsh-yzlin499-easy-plugins](https://github.com/yzlin499/dsh-yzlin499-easy-plugins) | <img alt="stars" src="https://img.shields.io/github/stars/yzlin499/dsh-yzlin499-easy-plugins?style=flat&color=4d6bfe" /> | A handy utility bundle for a bare-bones DSH |
-| [dong-victor/dsh-better-sidebar-starter](https://github.com/dong-victor/dsh-better-sidebar-starter) | <img alt="stars" src="https://img.shields.io/github/stars/dong-victor/dsh-better-sidebar-starter?style=flat&color=4d6bfe" /> | Run-configurations tab: IDEA-style Run/Debug configs (npm / springboot / python / custom) — one-click launch, history, WebSocket live logs (ANSI colors), parallel instances, cross-platform process-tree kill |
+| [dong-victor/dsh-apes-sidebar-starter](https://github.com/dong-victor/dsh-apes-sidebar-starter) | <img alt="stars" src="https://img.shields.io/github/stars/dong-victor/dsh-apes-sidebar-starter?style=flat&color=4d6bfe" /> | Run-configurations tab: IDEA-style Run/Debug configs (npm / springboot / python / custom) — one-click launch, history, WebSocket live logs (ANSI colors), parallel instances, cross-platform process-tree kill |
 | [baosfeng/my-dsh-plugins](https://github.com/baosfeng/my-dsh-plugins) | <img alt="stars" src="https://img.shields.io/github/stars/baosfeng/my-dsh-plugins?style=flat&color=4d6bfe" /> | Personal multi-plugin collection (`dsh-file-activity`): a sidebar file-activity tab recording read / added / modified history and stats, flat-browsed by folder, opened with the native preview |
 | [Hoemr/dsh-better-overleaf](https://github.com/Hoemr/dsh-better-overleaf) | <img alt="stars" src="https://img.shields.io/github/stars/Hoemr/dsh-better-overleaf?style=flat&color=4d6bfe" /> | Overleaf tab: direct-CDP browser login (third-party Chromium supported), project switching, local git mirrors under the workspace with two-way sync |
 
@@ -238,7 +241,7 @@ The GitHub topic [`dsh-better-sidebar`](https://github.com/topics/dsh-better-sid
 |---|---|---|
 | [HuanLinOTO/dsh-plugin-better-sidebar-plugin-office](https://github.com/HuanLinOTO/dsh-plugin-better-sidebar-plugin-office) | <img alt="stars" src="https://img.shields.io/github/stars/HuanLinOTO/dsh-plugin-better-sidebar-plugin-office?style=flat&color=4d6bfe" /> | Office-suite preview (.docx / .xlsx / .pptx) as a separate bundle to slim the core (in the official recommended catalog) |
 | [zemul/dsh-video-preview](https://github.com/zemul/dsh-video-preview) | <img alt="stars" src="https://img.shields.io/github/stars/zemul/dsh-video-preview?style=flat&color=4d6bfe" /> | Inline video preview: .mp4 / .webm / .mov / .mkv / .avi with a /video host route supporting HTTP Range scrubbing |
-| [dong-victor/dsh-better-sidebar-jupyter](https://github.com/dong-victor/dsh-better-sidebar-jupyter) | <img alt="stars" src="https://img.shields.io/github/stars/dong-victor/dsh-better-sidebar-jupyter?style=flat&color=4d6bfe" /> | Runnable `.ipynb` notebook view: lazy-start Python kernel, streaming outputs, save-back |
+| [dong-victor/dsh-apes-sidebar-jupyter](https://github.com/dong-victor/dsh-apes-sidebar-jupyter) | <img alt="stars" src="https://img.shields.io/github/stars/dong-victor/dsh-apes-sidebar-jupyter?style=flat&color=4d6bfe" /> | Runnable `.ipynb` notebook view: lazy-start Python kernel, streaming outputs, save-back |
 
 </details>
 
@@ -249,13 +252,13 @@ The GitHub topic [`dsh-better-sidebar`](https://github.com/topics/dsh-better-sid
 
 | Plugin | ⭐ | Description |
 |---|---|---|
-| [dong-victor/dsh-better-sidebar-terminal-plus](https://github.com/dong-victor/dsh-better-sidebar-terminal-plus) | <img alt="stars" src="https://img.shields.io/github/stars/dong-victor/dsh-better-sidebar-terminal-plus?style=flat&color=4d6bfe" /> | Terminal enhancement: bundled Nerd Font icons, xterm glyph fixes, stable terminal cwd |
+| [dong-victor/dsh-apes-sidebar-terminal-plus](https://github.com/dong-victor/dsh-apes-sidebar-terminal-plus) | <img alt="stars" src="https://img.shields.io/github/stars/dong-victor/dsh-apes-sidebar-terminal-plus?style=flat&color=4d6bfe" /> | Terminal enhancement: bundled Nerd Font icons, xterm glyph fixes, stable terminal cwd |
 | [Max-Null/dsh-sidebar-preview-select](https://github.com/Max-Null/dsh-sidebar-preview-select) | <img alt="stars" src="https://img.shields.io/github/stars/Max-Null/dsh-sidebar-preview-select?style=flat&color=4d6bfe" /> | Preview selection boost: select text in any sidebar preview → floating "send to session" |
 | [Hoemr/dsh-quicklook](https://github.com/Hoemr/dsh-quicklook) | <img alt="stars" src="https://img.shields.io/github/stars/Hoemr/dsh-quicklook?style=flat&color=4d6bfe" /> | QuickLook-style Space preview: press Space on the active file tab for a full-size image / PDF / text overlay; Space or Esc closes |
 
 </details>
 
-> 📣 **List your plugin**: tag your repo with the `dsh-better-sidebar` topic to appear on the [topic page](https://github.com/topics/dsh-better-sidebar); then PR one `PluginEntry` into [`src/client/plugins-tabs.ts`](./src/client/plugins-tabs.ts) / [`src/client/plugins-viewers.ts`](./src/client/plugins-viewers.ts) to join the built-in recommended catalog (data integrity is guarded by `tests/plugin-list.spec.ts`).
+> 📣 **List your plugin**: tag your repo with the `dsh-apes-sidebar` topic to appear on the [topic page](https://github.com/topics/dsh-apes-sidebar); then PR one `PluginEntry` into [`src/client/plugins-tabs.ts`](./src/client/plugins-tabs.ts) / [`src/client/plugins-viewers.ts`](./src/client/plugins-viewers.ts) to join the built-in recommended catalog (data integrity is guarded by `tests/plugin-list.spec.ts`).
 
 ## 🆕 Recent Updates
 
@@ -264,11 +267,43 @@ The GitHub topic [`dsh-better-sidebar`](https://github.com/topics/dsh-better-sid
   <a href="https://github.com/user-attachments/assets/946f7028-4967-461e-a750-d1b5056b62d0"><img width="33%" alt="Service API base screenshot" src="https://github.com/user-attachments/assets/946f7028-4967-461e-a750-d1b5056b62d0" /></a>
 </div>
 
-**Supported DSH versions**: <a href="https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions"><img alt="Supported DSH versions (v0.18.1): 0.1.2-rc.1+" src="https://img.shields.io/badge/DSH-0.1.2--rc.1%2B-4d6bfe" /></a> · full release history on the [Releases](https://github.com/omdsh-dev/DSH-better-sidebar/releases) page
+**Supported DSH versions**: <a href="https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions"><img alt="Supported DSH versions (v0.19.1): 0.1.5-rc.1+ (verified on rc.2)" src="https://img.shields.io/badge/DSH-0.1.5--rc.1%2B_%28verified_rc.2%29-4d6bfe" /></a> · full release history on the [Releases](https://github.com/omdsh-dev/DSH-better-sidebar/releases) page
+
+### v0.19.1
+
+> 📌 **Stable release** (npm `latest`, no prerelease suffix): the pinned baseline moves to **DSH 0.1.5-rc.2** (npm `next`) while the **peer floor stays `^0.1.5-rc.1`** — nothing in the rc.2 upstream delta touches this plugin (zero changes under `packages/api|host|session|agent`; the only real code edits are the message-feedback dialog, deliverables card CSS and the `CodeFileIcon` SVG data split), so rc.1 hosts need no DSH upgrade to run this version. Hosts on DSH 0.1.5-alpha.2 stay on **v0.19.0-alpha.1**; the 0.1.2-rc.1 stable line keeps using **v0.18.1**.
+
+- 🎯 **Adapted to DSH 0.1.5-rc.2**: devDependency pins, the CI mount lane and `SIDEBAR_SERVICE_VERSION` all move to rc.2; there is **no plugin-side code change** (the upstream delta does not touch this plugin — file-by-file audit in [docs/plans/2026-09-10-dsh-0.1.5-rc.2-adaptation.md](docs/plans/2026-09-10-dsh-0.1.5-rc.2-adaptation.md): the vast majority of the 300 changed files are single-line `version` bumps).
+- 🎨 **File icons (#611) and the built-in tab glyphs are now colored** (#531 + #594 merged, implementation redone for rc.2):
+  - **Files and folders use DSH's own artwork**: the fallback link is the host's `FileTypeIcon` from `ui-primitives` (48 full-color official code/config glyphs plus the category-colored sheets for markdown, images, PDF, Office, video and folders), so the plugin **ships no extension table and needs no icon chunk** — #429's 563-entry color dataset and `lib/client-file-icons.js` (255 kB) are gone, along with the `fileIconTheme` switch. Color is simply the behaviour now, and the core bundle grew by 10 kB.
+  - **New public `registerFileIcon` API** (capability `'fileIcons'`): register your own glyphs by extension (`exts`), exact file name (`names`) or directory name (`folderNames`), ranked by priority then registration order. **Caveat**: the host classifier covers every path, so a catch-all (`exts: []`) claims every row the specific rules miss.
+  - **Colored built-in tab glyphs**: Files / Changes / Tasks / Side chat / Terminal / Browser and the diff view all get a colored glyph, painted from `--dsw-alias-*` tokens so every skin still applies.
+  - **The native right Sidebar's tab chips carry a glyph too**: the host's tab definition has no icon field, but the `sidebar.right.pane.tab.title` slot *is* the chip's content — the plugin renders `[glyph][title]` there (an editor tab with a path shows that file's icon). The glyph is `aria-hidden`, so the chip's accessible name is unchanged.
+- 🛠 **CI fix 1: real Windows-lane timeouts**. `ci-windows` went red eight times in the 2026-09-09/10 window; six of those were process-spawning cases hitting vitest's 5000 ms default: `tests/agent-pty.spec.ts` (real PowerShell + ConPTY per terminal) and `tests/install-powershell.spec.ts` (a cold `powershell.exe` start measured 12.1 s) now declare a 30 s budget each, vitest.config.ts raises the global `testTimeout` from its 5000 ms default to **15 s** (the first real Windows run then lost a *third* file to the same default — `tests/git.spec.ts:85` at 9607 ms; three files, one cause, so per-file patches were whack-a-mole), and `waitForTranscript`'s inner poll budget dropped from 5000 ms to 15 s — **the inner budget must sit below the outer one** (they used to be the same 5000 ms, a structurally guaranteed timeout). `ci-windows`'s `Test` step now runs `pnpm test:windows` (`--maxWorkers=2`) so the process-spawning specs stop starving each other on a 2-core runner.
+- 🛠 **CI fix 2: the mount lane's npm install**. `plugin-mount`'s `npm install -g @deepseek-ai/dsh@<ver>` failed four times (two `ETARGET`, two `JavaScript heap out of memory` / exit 134): the pinned version declares its transitives as floating `^` ranges, so while upstream publishes a prerelease in stages (rc.2 appeared package by package between 14:43 and 14:57 UTC on 09-10) npm resolved a mixed rc.1/rc.2 peer graph (3062 ERESOLVE lines). The lane now pins an **already-complete** rc.2 (fixes ETARGET) and passes `NODE_OPTIONS=--max-old-space-size=4096` (fixes the OOM). `--legacy-peer-deps` was tried on the way and rejected by real CI: it skips exactly the peers a global install must supply, and `@deepseek-ai/cordis-plugin-group` — required at boot by `dsh-app-boot` — is a peer rather than a dependency, so the CLI died with `ERR_MODULE_NOT_FOUND`.
+
+### v0.19.0
+
+> 📌 **Stable release** (npm `latest`, no prerelease suffix): supports **DSH 0.1.5-rc.1+** only (peer floor `^0.1.5-rc.1`, CI pins `@deepseek-ai/dsh@0.1.5-rc.1`). Hosts on DSH 0.1.5-alpha.2 should stay on **v0.19.0-alpha.1** (the npm `alpha` tag still points there); the 0.1.2-rc.1 stable line keeps using **v0.18.1**.
+
+**✨ New**
+
+- 📝 **The new-tab list gets an optional description back**: DSH 0.1.5-rc.1 restored `SidebarRightGuideEntry.description` (optional), so the plugin restores `TabDescriptor.description` — each of the six built-in types declares a line again (all six guide rows — Files / Changes / Tasks / Side chat / Terminal / Browser — carry one), and the `guideDesc*` keys return to all 20 dictionaries. **The host's native guide renders descriptions only while the listed entries are ≤ 4** (a longer list drops every description rather than truncating), and the plugin contributes six guide entries by default — so in the default composition no description is rendered; they appear once the reader disables enough tab types (per-type switches live on the plugin's settings page) to bring the guide down to four entries or fewer. An entry that declares none stays a single icon + title line (the plugin ships no generic fallback sentence). (#613)
+
+**🐛 Fixes**
+
+- None. The rc.1 delta over alpha.2 is small (373 changed files, overwhelmingly upstream package version bumps, native-sidebar preview UI polish, and test snapshots); apart from the restored description field (plus upstream's `files` type now using its own coloured folder glyph as the guide glyph) nothing needed adapting.
+
+**🧰 CI & internals**
+
+- Baseline moved to **DSH 0.1.5-rc.1+** (#613): peer floor, devDependency pins, the CI mount lane, and `dsh.plugin.json`'s `engines.dsh` all follow (rc.1 is both the `latest` and `next` dist-tag on npm).
+- Explicitly unchanged, no need to re-check: the global main-panel model (the `main` slot / `sidebar.panellist` / `ctx.layout` / root-scoped `rightbar` + `rightbar.session`, still not adopted), the file address grammar (`packages/util/workspace-path` only had its version bumped), the native tab-body host contract (`.paneBody` is still a block scroller with a definite height), the core / agent / session / subagent host APIs, and the `ui-primitives` export surface (only CodeBlock rendering changed).
+- `@deepseek-ai/dsh-client-ui-primitives@0.1.5-rc.1` still declares no `dependencies` while its bundle still bare-imports `anser` / `shiki` / `@shikijs/langs/*` / `mdast-util-*` / `micromark-*` / `katex` — the third-party devDependencies hoisted in the previous release therefore stay, and must not be reverted.
+- Real-host verification (DSH 0.1.5-rc.1 + plugin 0.19.0): `typecheck` / `lint` / `check:consumer-types` green; unit suite **124 files · 1296 passed · 9 skipped**; `pnpm peers check` clean; the mount smoke lane against real rc.1 **7 passed** (including the tab-body fill assertion and the new "descriptions render only at ≤4 guide entries" assertion); on the local 3080 instance the guide still shows six icon+title capsules (6 > 4, so upstream renders no descriptions — upstream also raised the capsule `min-height` from 48px to 56px), clicking `AGENTS.md` in the file tree lands in the plugin editor (CodeMirror mounted), the side-chat composer sits on the pane floor (host box 962px == pane body 962px, composer 8px off the bottom), the bottom workbench's edges coincide with the centre column, and `pageerror` is 0 (the only console noise is the third-party `dsh-tauri-worktree` `/api/dsh-worktree/attach` 500, unrelated to this change).
 
 ### v0.19.0-alpha.1
 
-> 🧪 **alpha channel** (npm dist-tag `alpha`, install `dsh-better-sidebar@alpha`): supports **DSH 0.1.5-alpha.2+** only (peer floor `^0.1.5-alpha.2`, CI pins `@deepseek-ai/dsh@0.1.5-alpha.2`). Stay on **v0.19.0-alpha.0** for 0.1.5-alpha.1; the 0.1.2-rc.1 stable line keeps using **v0.18.1** (npm `latest`).
+> 🧪 **alpha channel** (npm dist-tag `alpha`, install `dsh-apes-sidebar@alpha`): supports **DSH 0.1.5-alpha.2+** only (peer floor `^0.1.5-alpha.2`, CI pins `@deepseek-ai/dsh@0.1.5-alpha.2`). Stay on **v0.19.0-alpha.0** for 0.1.5-alpha.1; the 0.1.2-rc.1 stable line keeps using **v0.18.1** (npm `latest`).
 
 **✨ New**
 
@@ -286,7 +321,7 @@ The GitHub topic [`dsh-better-sidebar`](https://github.com/topics/dsh-better-sid
 
 ### v0.19.0-alpha.0
 
-> 🧪 **alpha channel** (npm dist-tag `alpha`, install `dsh-better-sidebar@alpha`): supports **DSH 0.1.5-alpha.1+** only (peer floor `^0.1.5-alpha.1`, CI pins `@deepseek-ai/dsh@0.1.5-alpha.1`). The 0.1.2-rc.1 stable line keeps using **v0.18.1** (npm `latest`).
+> 🧪 **alpha channel** (npm dist-tag `alpha`, install `dsh-apes-sidebar@alpha`): supports **DSH 0.1.5-alpha.1+** only (peer floor `^0.1.5-alpha.1`, CI pins `@deepseek-ai/dsh@0.1.5-alpha.1`). The 0.1.2-rc.1 stable line keeps using **v0.18.1** (npm `latest`).
 
 **✨ New**
 
@@ -325,7 +360,7 @@ The GitHub topic [`dsh-better-sidebar`](https://github.com/topics/dsh-better-sid
 
 ### v0.18.0
 
-> 📌 **Stable release** (npm `latest`): this release targets **DSH 0.1.2-rc.1+ only** (peer floor `^0.1.2-rc.1`); 0.1.0-rc.8 ~ 0.1.1-rc.2 are not supported — stable-DSH users should stay pinned to `dsh-better-sidebar@0.17.1`, hosts on 0.1.2-alpha.x keep `dsh-better-sidebar@alpha` (v0.18.0-alpha.0).
+> 📌 **Stable release** (npm `latest`): this release targets **DSH 0.1.2-rc.1+ only** (peer floor `^0.1.2-rc.1`); 0.1.0-rc.8 ~ 0.1.1-rc.2 are not supported — stable-DSH users should stay pinned to `dsh-apes-sidebar@0.17.1`, hosts on 0.1.2-alpha.x keep `dsh-apes-sidebar@alpha` (v0.18.0-alpha.0).
 
 All changes since v0.17.1 (the two intermediate version numbers v0.18.1-alpha.0 / v0.19.0-alpha.0 were never published; their content is folded into this release):
 
@@ -356,7 +391,7 @@ All changes since v0.17.1 (the two intermediate version numbers v0.18.1-alpha.0
 
 **🌐 Ecosystem**
 
-- 10+ new curated plugins: dsh-better-sidebar-icons (#441), dsh-sidenote (#451, formerly dsh-sidechat #470), dsh-github-workbench (#410), dsh-bilingual-reader (#379), dsh-server-deck (#413), dsh-md-export (#405), dsh-code-nav (#404), dsh-suhuang-scroll (#392), dsh-better-overleaf (#370), and more (each with 18+ language i18n coverage)
+- 10+ new curated plugins: dsh-apes-sidebar-icons (#441), dsh-sidenote (#451, formerly dsh-sidechat #470), dsh-github-workbench (#410), dsh-bilingual-reader (#379), dsh-server-deck (#413), dsh-md-export (#405), dsh-code-nav (#404), dsh-suhuang-scroll (#392), dsh-better-overleaf (#370), and more (each with 18+ language i18n coverage)
 
 ### v0.19.0-alpha.0 (0.1.2-alpha.5 adaptation, unpublished, folded into v0.18.0)
 
@@ -366,13 +401,13 @@ All changes since v0.17.1 (the two intermediate version numbers v0.18.1-alpha.0
 
 ### v0.18.1-alpha.0
 
-> 🧪 **Alpha track**: this release targets **DSH 0.1.2-alpha.x only** (peer floor `^0.1.2-alpha.3`, npm dist-tag `alpha`, install `dsh-better-sidebar@alpha`). This version number was never published separately; its content is folded into the **v0.18.0** stable release.
+> 🧪 **Alpha track**: this release targets **DSH 0.1.2-alpha.x only** (peer floor `^0.1.2-alpha.3`, npm dist-tag `alpha`, install `dsh-apes-sidebar@alpha`). This version number was never published separately; its content is folded into the **v0.18.0** stable release.
 
 - 🔗 **Adapted to DSH 0.1.2-alpha.3 (published to npm, `alpha` dist-tag)**: the CI mount gate's pin, the `dsh.plugin.json` engines floor, and the `@deepseek-ai/*` peer / devDependencies baseline moved up to 0.1.2-alpha.3 (verified by a real-host mount smoke 14/14). All 117 commits between alpha.2 and alpha.3 were audited point by point: every host contract this plugin relies on (token auth, slash RPC, `MarkdownText` labels, the event-stream and persistence APIs behind `sidechat.events`, `SettingsNamespaceInput`, `SUBAGENT_DESCRIPTOR_VERSION` (still 3), `dsh-client-store`, the profile loader, the node-pty pin) is unchanged, so no code adaptation was needed; alpha.3's breaking changes (the required `BeginSubmissionInput.mode`, the renamed `attachment-invalid` subagent error, the removed SQLite persistence backend, the identity-gated projection change feed) were all verified not to touch this plugin.
 
 ### v0.18.0-alpha.0
 
-> 🧪 **Alpha track**: this release targets **DSH 0.1.2-alpha.x only** (peer floor `^0.1.2-alpha.2`, npm dist-tag `alpha`, install `dsh-better-sidebar@alpha`); 0.1.0-rc.8 ~ 0.1.1-rc.2 are no longer supported — stable-DSH users should stay on v0.17.1 (npm `latest`).
+> 🧪 **Alpha track**: this release targets **DSH 0.1.2-alpha.x only** (peer floor `^0.1.2-alpha.2`, npm dist-tag `alpha`, install `dsh-apes-sidebar@alpha`); 0.1.0-rc.8 ~ 0.1.1-rc.2 are no longer supported — stable-DSH users should stay on v0.17.1 (npm `latest`).
 
 - 🔗 **Adapted to DSH 0.1.2-alpha.2 (published to npm, `alpha` dist-tag)**: the CI mount gate's pin and the `@deepseek-ai/*` devDependencies baseline moved up to it (verified by a real-host mount smoke 14/14). Adaptation points: `dsh-settings` dropped the runtime `settingsNamespace` export (namespaces are now validated at compile time — the host passes the constant directly); the `dsh-subagent` descriptor version went 2→3 (stamped by the host package; the test assertion follows the `SUBAGENT_DESCRIPTOR_VERSION` constant); the restored `SessionEvent.ignorable` and the Remote gateway's unified `RemoteError` wrapping were verified to not affect this plugin.
 - 🐛 **Fixed blank Side Chat transcripts on DSH 0.1.2-alpha.1+**: transcript polling still called the `ctx.connection.api` face removed in alpha.1 (the error was silently swallowed, so the tab rendered an empty transcript forever). Transcripts now come from the plugin's own `sidechat.events` route (live threads read the in-memory event log, cold threads read session persistence, with `afterSeq` delta pulls, [sidechat-routes.ts](./src/sidechat-routes.ts)).
@@ -410,7 +445,7 @@ All changes since v0.15.2:
 **🐛 Fixes**
 
 - 🛒 **DSH marketplace managed-install compatibility** ([#338](https://github.com/omdsh-dev/DSH-better-sidebar/pull/338)): the public `cordis` entry was removed from `peerDependencies` (the market preview hard-rejects `cordis` in any dependency field — optional does not help), so the npm package satisfies the [dsh-community-market install rules](https://github.com/anywhere-labs/deepseek-harness-desktop/blob/master/dsh-community-market/docs/install-and-uninstall.zh.md) — catalog sources (dshfind / 1024Store) can re-issue the `repository_backlink` verified target and the plugin becomes installable through the Desktop market
-- 🔤 **Type base migrated to `@deepseek-ai/cordis`** ([#338](https://github.com/omdsh-dev/DSH-better-sidebar/pull/338)): the declaration surface (`src/context-types.ts`) no longer depends on or restates the public `cordis` — `Context` is now an **intersection** of the real vendored cordis Context with the structural service faces, and the `ctx.betterSidebar` type merge lives on `@deepseek-ai/cordis`. **Consumer migration**: change `import type { Context } from 'cordis'` to `import type { Context } from '@deepseek-ai/cordis'` (the `import type {} from 'dsh-better-sidebar'` merge path is unchanged); plugins that never used that import are unaffected
+- 🔤 **Type base migrated to `@deepseek-ai/cordis`** ([#338](https://github.com/omdsh-dev/DSH-better-sidebar/pull/338)): the declaration surface (`src/context-types.ts`) no longer depends on or restates the public `cordis` — `Context` is now an **intersection** of the real vendored cordis Context with the structural service faces, and the `ctx.betterSidebar` type merge lives on `@deepseek-ai/cordis`. **Consumer migration**: change `import type { Context } from 'cordis'` to `import type { Context } from '@deepseek-ai/cordis'` (the `import type {} from 'dsh-apes-sidebar'` merge path is unchanged); plugins that never used that import are unaffected
 - 🧩 **All internal `ctx.betterSidebar` reads fixed** ([#357](https://github.com/omdsh-dev/DSH-better-sidebar/pull/357), fixes [#356](https://github.com/omdsh-dev/DSH-better-sidebar/issues/356)): on npm-installed DSH 0.1.1-rc.x (web bundle) the sidebar died on every page load (`cannot get property "betterSidebar" without inject`) — the 26 internal direct reads now go through `ctx.get('betterSidebar')` (root reflect-store resolution, immune to the fiber chain); external consumers keep `inject: ['betterSidebar'] + ctx.betterSidebar`
 - 🔐 **Session-workspace boundary for file APIs** ([#345](https://github.com/omdsh-dev/DSH-better-sidebar/pull/345), fixes [#328](https://github.com/omdsh-dev/DSH-better-sidebar/issues/328)): fixed `fs.tree / fs.read / fs.write` workspace escapes; media, HTML preview and uploads share real-path symlink validation; regression tests for absolute paths, symlinks, uploads and nested Git sessions
 - 🪟 **Panel-host layering and viewport clipping** ([#330](https://github.com/omdsh-dev/DSH-better-sidebar/pull/330) [#278](https://github.com/omdsh-dev/DSH-better-sidebar/pull/278), fixes [#277](https://github.com/omdsh-dev/DSH-better-sidebar/issues/277)): panel host z-index 40→25 — below the DSH cordis dynamic-plugin layer (30), so the workbench no longer covers cordis inventory/approval surfaces (still above AppFrame's 20 and below the 100+ float stack); `overflow: hidden` on the host clips at the viewport edge, so collapsed panels no longer stretch the document into bidirectional scrolling (measured `scrollWidth` 2289→1672 / `scrollHeight` 1280→1032, any skin)
@@ -566,9 +601,9 @@ Full integration docs (complete fields, matching algorithm, HMR pitfalls, declar
 
 ### ➕ Add Plugins (recommended plugin catalog)
 
-The dashed cards at the end of the "Sidebar content" / "File viewers" grids in the "Side Cards" settings section open the **Add tab plugins** / **Add preview plugins** modals: each declares its open extension point, offers a "**Browse more plugins on GitHub**" button (the [GitHub topic `dsh-better-sidebar`](https://github.com/topics/dsh-better-sidebar)), and lists the recommended catalog (name / repo / description / install script) — "**Open**" jumps to the repo, "**Copy**" writes the install command to the clipboard.
+The dashed cards at the end of the "Sidebar content" / "File viewers" grids in the "Side Cards" settings section open the **Add tab plugins** / **Add preview plugins** modals: each declares its open extension point, offers a "**Browse more plugins on GitHub**" button (the [GitHub topic `dsh-apes-sidebar`](https://github.com/topics/dsh-apes-sidebar)), and lists the recommended catalog (name / repo / description / install script) — "**Open**" jumps to the repo, "**Copy**" writes the install command to the clipboard.
 
-**Curating a new plugin**: append a `PluginEntry` to [`src/client/plugins-tabs.ts`](./src/client/plugins-tabs.ts) (tab registrations) or [`src/client/plugins-viewers.ts`](./src/client/plugins-viewers.ts) (file-previewer registrations) and tag your repo with the `dsh-better-sidebar` topic; data integrity is guarded by `tests/plugin-list.spec.ts`.
+**Curating a new plugin**: append a `PluginEntry` to [`src/client/plugins-tabs.ts`](./src/client/plugins-tabs.ts) (tab registrations) or [`src/client/plugins-viewers.ts`](./src/client/plugins-viewers.ts) (file-previewer registrations) and tag your repo with the `dsh-apes-sidebar` topic; data integrity is guarded by `tests/plugin-list.spec.ts`.
 
 ## 🛠️ Development & Build
 
@@ -628,7 +663,7 @@ WeChat / QQ group QR codes will live here. After uploading the QR images (drag t
 ## 🤝 Contributing
 
 - **Code changes go through PRs**: develop on a `feat/*` / `fix/*` branch, then `gh pr create`; docs-only changes may be pushed to main directly
-- **Curate an ecosystem plugin**: tag your repo with `dsh-better-sidebar` + PR a `PluginEntry` into [`src/client/plugins-tabs.ts`](./src/client/plugins-tabs.ts) / [`plugins-viewers.ts`](./src/client/plugins-viewers.ts)
+- **Curate an ecosystem plugin**: tag your repo with `dsh-apes-sidebar` + PR a `PluginEntry` into [`src/client/plugins-tabs.ts`](./src/client/plugins-tabs.ts) / [`plugins-viewers.ts`](./src/client/plugins-viewers.ts)
 - **Before submitting**: `pnpm typecheck && pnpm build && pnpm test` (or `make check` for the one-shot aggregate; CI additionally gates on npm-pack → real-mount → headless-render via `pnpm test:mount`, plus the aggregate double-mount regression `pnpm test:mount:aggregate`)
 - See [`AGENTS.md`](./AGENTS.md) for the repository rules (hard constraints, CI lanes, release flow)
 
@@ -659,5 +694,5 @@ Thanks to everyone who contributed:
 ---
 
 <div align="center">
-  <sub>MIT License · Built for the <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a> ecosystem · discover more on the <a href="https://github.com/topics/dsh-better-sidebar">dsh-better-sidebar topic</a></sub>
+  <sub>MIT License · Built for the <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a> ecosystem · discover more on the <a href="https://github.com/topics/dsh-apes-sidebar">dsh-apes-sidebar topic</a></sub>
 </div>

cordis.patch.yml

@@ -1,12 +1,12 @@
-# dsh-better-sidebar bundle patch
+# dsh-apes-sidebar bundle patch
 #
 # This file is the `dsh.bundle.patch` layer of the published npm package: when
 # the plugin is installed through the official CLI —
 #
-#   dsh plugin --profile <name> add dsh-better-sidebar@<version>
+#   dsh plugin --profile <name> add dsh-apes-sidebar@<version>
 #
 # — the command reconciles `dsh.profile.bundles` against installed packages
-# and, seeing this declaration, appends `dsh-better-sidebar` to the bundle
+# and, seeing this declaration, appends `dsh-apes-sidebar` to the bundle
 # stack. The profile boot then merges THIS patch (a single `insert` of the
 # plugin row) exactly like the manual cordis.patch.yml mount line used
 # before. No profile file edits needed — one command installs and mounts.
@@ -23,7 +23,7 @@
 #
 #   - insert:
 #       - id: better-sidebar
-#         name: 'dsh-better-sidebar'
+#         name: 'dsh-apes-sidebar'
 #         config:
 #           shell: /bin/zsh
 #           shellArgs:
@@ -35,7 +35,7 @@
 # `web-ui-better-sidebar`). Two mounts register /sidebar/api twice and fail the
 # whole plugin tree at boot ("duplicate prefix route"). The `!!js` disabled
 # expression backs THIS row off when another *enabled* entry already mounts
-# `dsh-better-sidebar`; the aggregate instance then owns the sidebar. The
+# `dsh-apes-sidebar`; the aggregate instance then owns the sidebar. The
 # loader evaluates it when this row is processed (entry-list order, only rows
 # before this one are visible), so the aggregate bundle must precede this one
 # in `dsh.profile.bundles` — the standard install order, since `dsh plugin add`
@@ -45,5 +45,5 @@
 # fail loudly at the loader as before.
 - insert:
     - id: better-sidebar
-      name: 'dsh-better-sidebar'
-      disabled: !!js "[...ctx.loader.entries()].some((e) => e.options.name === 'dsh-better-sidebar' && e.options.id !== 'better-sidebar' && !e.disabled)"
+      name: 'dsh-apes-sidebar'
+      disabled: !!js "[...ctx.loader.entries()].some((e) => e.options.name === 'dsh-apes-sidebar' && e.options.id !== 'better-sidebar' && !e.disabled)"

docs/external-plugin-guide.md

@@ -1,8 +1,8 @@
-# 外部插件接入指南：基于 dsh-better-sidebar 实现新页面
+# 外部插件接入指南：基于 dsh-apes-sidebar 实现新页面
 
 > 面向 **消费插件开发者**：如何让你的插件向 better-sidebar 注册新的侧边栏页面（tab）和文件类型预览器。
 >
-> 适用版本：**v0.4.0+**（`ctx.betterSidebar` 服务）；声明式设置 **v0.4.1+**；text/number 设置行 **v0.11.0+**；badge/生命周期/定向打开/插件设置/版本探测 **v0.12.0+**；select 设置行（`settingSelect`）与外链认领（`urlTarget`）**v0.13.0+**；统一 `@deepseek-ai/cordis` 类型基底 **v0.15.2+**；终端固定（pin）**v0.17.0+**。当前版本 **v0.19.0-alpha.1**（alpha 通道，仅支持 DSH **0.1.5-alpha.2+**；**0.1.5-alpha.1 不再支持**——alpha.1 用户请用 v0.19.0-alpha.0，那是它的最后一版；0.1.2-rc.1 稳定线请用 v0.18.x）。**v0.19.0 移除了自绘右侧面板与自由窗口**（见 §0、§11）。
+> 适用版本：**v0.4.0+**（`ctx.betterSidebar` 服务）；声明式设置 **v0.4.1+**；text/number 设置行 **v0.11.0+**；badge/生命周期/定向打开/插件设置/版本探测 **v0.12.0+**；select 设置行（`settingSelect`）与外链认领（`urlTarget`）**v0.13.0+**；统一 `@deepseek-ai/cordis` 类型基底 **v0.15.2+**；终端固定（pin）**v0.17.0+**。当前版本 **v0.19.1**（正式版，npm `latest`，仅支持 DSH **0.1.5-rc.1+**，已在 **0.1.5-rc.2** 上完成真机挂载验证；**0.1.5-alpha.2 及更早不再支持**——alpha.2 用户请用 v0.19.0-alpha.1，那是它的最后一版；0.1.2-rc.1 稳定线请用 v0.18.x）。**v0.19.0 移除了自绘右侧面板与自由窗口**（见 §0、§11）。
 > 权威代码：`src/client/service.ts`（服务实现）、`src/client/builtins/`（内置 8 tab + 6 viewer 参考实现）、`lib/types/client/service.d.ts`（类型声明）。
 > 仓库开发规则（硬约束 / CI / 发版）见 [AGENTS.md](../AGENTS.md)。
 
@@ -27,7 +27,7 @@
 | 内置类型接管 | 插件的 `editor` 类型以 `extension` 优先级认领 `dsh-resource://file/**`（压过内置 `ui-sidebar-documentpreview` 的 `text` 预览——即 `fallback` 带），并接管内置 `files` 页面 kind（`openTab('files')` 打开插件的文件树）；插件卸载/禁用时内置实现自动复位 |
 | 终端上限 | 终端 tab 的数量上限只统计插件自己底部工作台里的终端；原生栏里的终端不计入 |
 | 底部工作台的开合 | 落到底部工作台的打开一律展开它（新建与聚焦都算），因此 `openTab` 的落点永远可见；开合按钮注册在 DSH 会话头的 utilities 槽（`conversation.session.header.utilities`），不在插件自己的宿主里 |
-| 新建标签页列表 | 每个 tab 类型在原生 guide 里占一行：标题取 `title` + 图标取 `icon`（**无第二行说明**——alpha.2 起原生指南把条目渲染成「图标+标题」胶囊，`description` 已从宿主契约删除，插件随之移除 `TabDescriptor.description` 与 6 个 `guideDesc*` 词条）；`hidden: true` 的类型不占行。插件的 `editor` 类型不再单独占行（它认领的文件资源由 `files` 接管页承载同一视图） |
+| 新建标签页列表 | 每个 tab 类型在原生 guide 里占一行：标题取 `title` + 图标取 `icon`（缺图标时宿主补一个方块占位），说明取可选的 `description`——**宿主只在 guide 列出的条目 ≤ 4 条时渲染说明**（上游 `MAX_DESCRIBED_ENTRIES = 4`），更长的列表整列丢掉所有说明；未声明 `description` 的条目渲染成单行「图标 + 标题」（rc.1 起 `description` 回到宿主契约，但**宿主与插件都没有兜底句**，所以插件恢复字段而不恢复旧的通用句）；`hidden: true` 的类型不占行。插件的 `editor` 类型不再单独占行（它认领的文件资源由 `files` 接管页承载同一视图）。**注意默认组合看不到说明**：插件贡献 6 个 guide 条目（文件 / 文件变动 / 任务管理 / 侧边对话 / 终端 / 浏览器），已超过 4 条上限——要让说明出现，需在插件设置页关掉足够多的 tab 类型把 guide 压到 ≤ 4 条 |
 | 新建面板的种子（alpha.2） | 在新会话打开原生新面板时，宿主从已注册的 guide 条目里播种：恰好 1 个条目 → 直接打开那一页；0 或 ≥2 个条目 → 打开指南。`revealIfOpened` 打开的「页面」在**同一 pane 内**强制去重（已在该 pane 就不再新建）；由已有 tab 地址驱动的打开不受该去重影响 |
 | alpha.2 全局面板（不接入） | 插件**不采用** alpha.2 引入的全局主面板模型——根级 keyed `main` 槽（预留 key `conversation`，由 ui-conversation 注册为 `main.conversation`）、根级 `sidebar.panellist` 列表槽（`SidebarPanelMetadata` / `SidebarPanelIconOwnerProps`）、`ctx.layout.selectPanel(MainPanelId|null)` / `beginNavigation()` / `dispose()`、全局标准 prop `usePanelInfo`，以及改根级并新增会话级 `rightbar.session` 子槽的 `rightbar`——这些只作兼容保留，不向其迁移 |
 | 已移除 | 插件自绘右侧面板（含宽度拖拽 / 新会话默认宽度）与**自由窗口**（`features` 里的 `'floatWindows'` 已删除，v0.18.x 及更早版本的消费者请勿再 gate 该能力）；`openByDefault` / `defaultWidthPercent` / `changesDiffFloat` 三个设置项同步删除（旧文档里的键会被忽略） |
@@ -56,7 +56,7 @@ better-sidebar 从 v0.4.0 起把自己改造成一个**注册表服务**：
 DSH 运行时和生态的类型正主是 vendored `@deepseek-ai/cordis`。你的插件解析到它的 `Context` 时，`ctx.betterSidebar` 不会自动出现——由 better-sidebar 用 `declare module '@deepseek-ai/cordis'` 补上：
 
 ```ts
-import type {} from 'dsh-better-sidebar'  // 触发 declare module '@deepseek-ai/cordis' 类型合并
+import type {} from 'dsh-apes-sidebar'  // 触发 declare module '@deepseek-ai/cordis' 类型合并
 ```
 
 这个 **type-only import** 在编译时被擦除，不产生任何运行时依赖，也不会触发构建纯度门（见 §10）。
@@ -68,15 +68,15 @@ import type {} from 'dsh-better-sidebar'  // 触发 declare module '@deepseek-ai
   "name": "my-plugin",
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "dsh-better-sidebar": "workspace:*"
+    "dsh-apes-sidebar": "workspace:*"
   },
   "peerDependenciesMeta": {
-    "dsh-better-sidebar": { "optional": true }
+    "dsh-apes-sidebar": { "optional": true }
   }
 }
 ```
 
-- `dsh-better-sidebar` 必须是 **peerDependency**（不是 dependency），避免两份实例；
+- `dsh-apes-sidebar` 必须是 **peerDependency**（不是 dependency），避免两份实例；
 - `optional: true`：better-sidebar 未安装时你的插件照常加载，注册代码因为 `ctx.betterSidebar` 为 undefined 而安全跳过。
 
 > ⚠️ **计划上架 DSH 插件市场**的插件还须遵守市场 manifest 约束（`dependencies`/`peerDependencies`/`optionalDependencies` 一律不得出现 `cordis`、`scripts` 不得含 install 类钩子），详见 [AGENTS.md](../AGENTS.md) 硬约束一节。
@@ -92,10 +92,10 @@ import type {
   FileViewerDescriptor,
   FileViewerProps,
   FileFetchStrategy,
-} from 'dsh-better-sidebar'
+} from 'dsh-apes-sidebar'
 
 // 方式二：子路径（与主入口等价）
-import type { TabDescriptor } from 'dsh-better-sidebar/client/service'  // 别名 ./client/api
+import type { TabDescriptor } from 'dsh-apes-sidebar/client/service'  // 别名 ./client/api
 ```
 
 v0.12.0 起，服务模块还 re-export 了完整的状态词汇表，消费者可以直接命名（不再只能靠推断）：
@@ -104,10 +104,10 @@ v0.12.0 起，服务模块还 re-export 了完整的状态词汇表，消费者
 import type {
   SidebarTab, SidebarState, SidebarStore, SidebarSnapshot, SidebarDiffRef, TabType,
   SessionScope, SidebarPrefs, OpenTabSeed, SidebarSettingsRenderProps,
-} from 'dsh-better-sidebar/client/service'
+} from 'dsh-apes-sidebar/client/service'
 ```
 
-> 💡 **类型合并触发路径**：`import type {} from 'dsh-better-sidebar/client/service'` 同样会加载 `Context` 的 augmentation（`declare module '@deepseek-ai/cordis'` 在 context-types.d.ts 中）——**纯浏览器侧插件建议走 `client/service` 路径**，避免拉进宿主半的 Node 类型图（主入口 `dsh-better-sidebar` 的声明面含宿主代码；宿主消费者本就处于 Node 环境则无所谓）。client 可达声明图（`client/*` + context-types + html-route + prefs-shared）自 v0.12.0 起**零 Node 依赖**（`scripts/check-consumer-types.sh` 守护），没有 `@types/node`、`skipLibCheck: false` 也能编译。
+> 💡 **类型合并触发路径**：`import type {} from 'dsh-apes-sidebar/client/service'` 同样会加载 `Context` 的 augmentation（`declare module '@deepseek-ai/cordis'` 在 context-types.d.ts 中）——**纯浏览器侧插件建议走 `client/service` 路径**，避免拉进宿主半的 Node 类型图（主入口 `dsh-apes-sidebar` 的声明面含宿主代码；宿主消费者本就处于 Node 环境则无所谓）。client 可达声明图（`client/*` + context-types + html-route + prefs-shared）自 v0.12.0 起**零 Node 依赖**（`scripts/check-consumer-types.sh` 守护），没有 `@types/node`、`skipLibCheck: false` 也能编译。
 
 ---
 
@@ -115,7 +115,7 @@ import type {
 
 ```ts
 // my-plugin/src/client/index.ts
-import type {} from 'dsh-better-sidebar'          // 触发 ctx.betterSidebar 类型合并
+import type {} from 'dsh-apes-sidebar'          // 触发 ctx.betterSidebar 类型合并
 import type { Context } from '@deepseek-ai/cordis'
 
 export const inject = ['betterSidebar', 'slots']   // 声明服务依赖（slots 可选，按需）
@@ -181,7 +181,15 @@ interface TabDescriptor {
   id: string
   /** 标题（i18n 友好：传字符串或返回字符串的函数） */
   title: string | (() => string)
-  /** 图标：ReactNode 或 (size: number) => ReactNode */
+  /**
+   * 一行说明，渲染在标题下方（DSH 原生右侧栏的新建标签页 / guide 列表）。
+   * **宿主只在 guide 列出的条目 ≤ 4 条时渲染它**（上游 `MAX_DESCRIBED_ENTRIES = 4`），
+   * 更长的列表整列丢掉所有说明——也就是说这是一行「锦上添花」，别把关键信息只放这里。
+   * 不声明就不发 `description` 字段：宿主没有兜底句，插件也不补（通用句在所有页面上
+   * 长得一样，纯噪音），条目就渲染成单行「图标 + 标题」。函数形式在渲染时求值，跟随语言。
+   */
+  description?: string | (() => string)
+  /** 图标：ReactNode 或 (size: number) => ReactNode（不声明时宿主补一个方块占位） */
   icon?: ReactNode | ((size: number) => ReactNode)
   /** + 菜单排序（升序）；默认 100。内置：editor=10, git=20, subagent=30, sidechat=35, terminal=40, browser=50 */
   order?: number
@@ -575,10 +583,31 @@ interface BetterSidebarService {
   registerTab(descriptor: TabDescriptor): () => void
   /** 注册文件预览器；返回 disposer */
   registerFileViewer(descriptor: FileViewerDescriptor): () => void
+  /** 注册自定义文件树/文件 tab 图标（v0.19.0+，features 含 'fileIcons'）；返回 disposer */
+  registerFileIcon(descriptor: FileIconDescriptor): () => void
   /** 当前已注册的 tab 描述符快照（同步，供 useSyncExternalStore 用；含被设置页禁用的类型） */
   getTabs(): readonly TabDescriptor[]
   /** 当前已注册的 file viewer 描述符快照（含被设置页禁用的 viewer） */
   getFileViewers(): readonly FileViewerDescriptor[]
+  /** 当前已注册的文件图标描述符快照（v0.19.0+） */
+  getFileIcons(): readonly FileIconDescriptor[]
+  /** 按 path 匹配**具体**注册（priority 降序、注册序）：先 names 文件名，再
+   *  具体扩展名；不查 catch-all 与 folder 保留值。消费方一般直接用
+   *  fileIcon/folderIcon 全链解析器。 */
+  matchFileIcon(path: string): FileIconDescriptor | undefined
+  /** 匹配目录行注册：先按 folderNames 匹配目录名（name 传 basename，可省），
+   *  再按 'folder'/'folder-open' 保留扩展名；priority 降序、注册序；
+   *  返回 undefined = 回退内置 VscFolder/VscFolderOpened */
+  matchFolderIcon(open: boolean, name?: string): FileIconDescriptor | undefined
+  /** 文件图标权威解析器（v0.19.0+），完整回退链：
+   *  ① 具体 names/扩展名注册 → ② 内置 glyph（md/媒体/pdf/json/代码/配置/数据库/lock/压缩包）
+   *  → ③ 最优 catch-all 注册（exts: []，即全局默认）→ ④ 通用 VscFile。
+   *  任一注册工厂抛错都会被吞（console.error 后跳下一级），永远返回有效 ReactNode。 */
+  fileIcon(path: string, size: number): ReactNode
+  /** 目录图标解析器：注册的 folderNames/'folder'（闭合）/'folder-open'（展开）图标 →
+   *  内置 VscFolder/VscFolderOpened；path 为目录自身路径（主题可按目录变化），
+   *  open 会传给工厂，一条注册即可渲染开/合两态。 */
+  folderIcon(path: string, open: boolean, size: number): ReactNode
   /** 按 id 查 tab 描述符 */
   getTab(id: string): TabDescriptor | undefined
   /** 某个 tab 类型是否在 Side card 设置中启用（v0.4.1+；缺省 = 启用） */
@@ -613,7 +642,8 @@ interface BetterSidebarService {
   /** 能力清单（只增不删，唯一例外：v0.19.0 删除了 'floatWindows'）：
    *  'badge' | 'tabLifecycle' | 'updateTab' | 'openFile' | 'targetedOpen' |
    *  'stateSubscription' | 'tabMeta' | 'pluginSettings' | 'urlTarget' |
-   *  'settingSelect' ——用 `features.includes('xxx')` 按能力 gate。 */
+   *  'settingSelect' | 'fileIcons'
+   *  ——用 `features.includes('xxx')` 按能力 gate。 */
   readonly features: readonly string[]
   /** 当前快照：激活 sessionId + 其状态（面板几何/打开的 tabs/展开集）+ prefs。
    *  session 未激活时 state/sessionId 为 undefined。 */
@@ -644,8 +674,99 @@ interface OpenTabSeed {
    *  undefined = 不改，null = 显式清除 */
   meta?: unknown
 }
+
+/** 文件图标注册描述符（v0.19.0+，features 含 'fileIcons'）。 */
+interface FileIconDescriptor {
+  /** 唯一 id（如 'my-plugin:icons'） */
+  id: string
+  /** 小写扩展名、不带前导点（如 ['csv','tsv']）。两个**保留值**认领目录行
+   *  而非文件扩展名：'folder'（闭合目录）、'folder-open'（展开目录）——
+   *  它们不会匹配真实文件（名为 x.folder 的文件不受影响）。
+   *  [] = catch-all 全局默认：只兜内置 glyph 没认领的扩展名（注册的具体
+   *  names/扩展名与内置 glyph 永远优先于它）。
+   *  **省略** = 完全没有扩展名规则（只有 names 的注册不是 catch-all）。 */
+  exts?: readonly string[]
+  /** 精确**文件名**（basename，大小写不敏感，如 ['package.json','Dockerfile']）——
+   *  图标主题的 fileNames 半边；命中优先于扩展名。省略/[] = 无文件名规则。 */
+  names?: readonly string[]
+  /** 精确**目录名**（basename，大小写不敏感，如 ['node_modules','src']）——
+   *  图标主题的 folderNames 半边；命中优先于保留扩展名，且**只认领列出的
+   *  目录**（要接管所有目录请用 'folder'/'folder-open'）。省略/[] = 无规则。 */
+  folderNames?: readonly string[]
+  /** priority 高者胜，缺省 0（同级按注册先后） */
+  priority?: number
+  /** 尺寸感知的图标工厂（文件树/文件 tab 当前以 size=14 渲染）。
+   *  与内置图标（currentColor 单色，遵循皮肤契约）不同，注册图标可以是
+   *  任意 ReactNode——包括彩色图标；颜色在皮肤间的表现由注册方自行负责。
+   *  open：目录行的展开态（文件行为 undefined），一条注册即可渲染开/合两态。 */
+  icon: (path: string, size: number, open?: boolean) => ReactNode
+}
 ```
 
+**图标注册示例**（v0.19.0+；一次注册可同时覆盖具体扩展名、目录与全局默认）：
+
+```ts
+if (ctx.betterSidebar.features.includes('fileIcons')) {
+  ctx.effect(() =>
+    ctx.betterSidebar.registerFileIcon({
+      id: 'my-plugin:icons',
+      exts: ['csv', 'tsv'],
+      icon: (path, size) => <MyCsvIcon size={size} />, // 彩色也可以
+    })
+  )
+  ctx.effect(() =>
+    ctx.betterSidebar.registerFileIcon({
+      id: 'my-plugin:names', // 精确文件名：package.json 与别的 .json 区分开
+      names: ['package.json', 'Dockerfile'],
+      icon: (path, size) => <MyBrandIcon size={size} />,
+    })
+  )
+  ctx.effect(() =>
+    ctx.betterSidebar.registerFileIcon({
+      id: 'my-plugin:folders', // 只认领列出的目录名
+      folderNames: ['node_modules', 'src'],
+      icon: (path, size, open) => open === true ? <MyOpenFolderIcon size={size} /> : <MyFolderIcon size={size} />,
+    })
+  )
+  ctx.effect(() =>
+    ctx.betterSidebar.registerFileIcon({
+      id: 'my-plugin:all-folders', // 接管所有目录行（保留扩展名）
+      exts: ['folder', 'folder-open'],
+      icon: (path, size, open) => open === true ? <MyOpenFolderIcon size={size} /> : <MyFolderIcon size={size} />,
+    })
+  )
+  ctx.effect(() =>
+    ctx.betterSidebar.registerFileIcon({
+      id: 'my-plugin:default', // 全局默认：只兜内置 glyph 没认领的文件
+      exts: [],
+      icon: (path, size) => <MyGenericFileIcon size={size} />,
+    })
+  )
+}
+```
+
+**消费表面与回退链**（由本插件内置消费，插件无需自己接线）：
+
+- 文件树文件行 / 编辑器文件 tab（每个文件独立窗口）：`fileIcon(path, size)`
+  ——具体 `names`/扩展名注册 → catch-all 全局默认（`exts: []`）→ **DSH 官方图标**。
+- 文件树目录行（含根行）：`folderIcon(path, open, size)`——`folderNames` 命中
+  → `'folder'`/`'folder-open'` 保留扩展名 → DSH 官方的文件夹图形。
+
+注册/注销即时生效（文件树与 tab 栏订阅注册表变化自动重渲染）；图标工厂抛错会被吞掉
+（console.error 后跳到回退链下一级），不会空白行。
+
+**内置图标 = DSH 官方图形**（v0.19.0+，插件不含任何图标数据）：
+
+- 回退链末端是 `FileTypeIcon` / `CodeFileIcon`（`@deepseek-ai/dsh-client-ui-primitives`，
+  DSH 0.1.5-rc.2+）：48 个代码/配置类目的官方全彩图形 + markdown / 图片 / PDF / Word /
+  Excel / PPT / 视频 / 文件夹 / 通用文档的类目色板图形，分类器是宿主的
+  `classifyFileType`（精确文件名 → 前缀/后缀 → 项目上下文 → 扩展名）。本插件因此**没有**
+  自己的扩展名表、**没有**图标 chunk、**没有**图标主题开关——彩色是唯一形态。
+- **语义后果（重要）**：宿主分类器覆盖任意路径，所以「插件自己已经能画这个扩展名」不再是
+  拦住 catch-all 的理由——**注册了 `exts: []` 的插件会接管全部未具体命中的行**（优先级降序、
+  同优先级按注册序）。只想补几个扩展名就照常用 `exts`/`names`，别用 catch-all 兜底。
+- 插件自己注册的图标颜色由注册方负责（见 §12）：品牌色是内容标识而非 chrome。
+
 **版本与能力探测**（v0.12.0+）：消费插件先查能力再使用新 API，老版本（或旧 DSH）下优雅降级：
 
 ```ts
@@ -745,13 +866,13 @@ ctx.effect(() =>
 | 陷阱 | 说明 |
 |---|---|
 | **构建纯度门** | client bundle 禁止 value-import `@dsh-external/*` 或非白名单的 `@deepseek-ai/*`（`tsdown.config.ts` 的 `dsh-client-bundle-purity` 插件）；**类型 `import type {}` 会被擦除，不触发门禁**——类型可自由共享，运行时符号不行。所有跨插件交互走 `ctx.betterSidebar` 方法调用 |
-| **统一 cordis 分支（v0.15.2+）** | 类型基底与 augmentation 全部在 DSH 运行时正主 `@deepseek-ai/cordis` 上（`src/context-types.ts`：真实 cordis `Context` 与结构化服务面做**交集**，不再重述 `declare module 'cordis'`——host/client 包对同名成员声明不同会 TS2717）。消费者 `import type {} from 'dsh-better-sidebar'` 即拿到 `ctx.betterSidebar`，或直接 `import type { Context } from 'dsh-better-sidebar'`。公开版 `cordis` 不再被依赖 |
+| **统一 cordis 分支（v0.15.2+）** | 类型基底与 augmentation 全部在 DSH 运行时正主 `@deepseek-ai/cordis` 上（`src/context-types.ts`：真实 cordis `Context` 与结构化服务面做**交集**，不再重述 `declare module 'cordis'`——host/client 包对同名成员声明不同会 TS2717）。消费者 `import type {} from 'dsh-apes-sidebar'` 即拿到 `ctx.betterSidebar`，或直接 `import type { Context } from 'dsh-apes-sidebar'`。公开版 `cordis` 不再被依赖 |
 | **ModuleLoader 不跨插件** | 运行时 `require()` 虽支持跨 bundle，但被构建门挡；所有交互走 `ctx.betterSidebar` 方法调用 |
 | **host 半无此服务** | `ctx.betterSidebar` 只在 client 侧存在；host 半需要 better-sidebar 数据走 `/sidebar/api/*` HTTP 路由 |
 | **portal 限制** | 整面板 slot 由 ui-layout 独占，外部 tab 只能进入 better-sidebar 的 portal 内部，无法全屏替换整个面板 |
 | **id 冲突** | `registerTab` / `registerFileViewer` 对重复 id 抛错；建议用包前缀（`my-plugin:xxx`） |
-| **不要 value-import `dsh-better-sidebar`** | 即使是 `./client/service` 子路径，运行时落点也是 client bundle；只做 type-only import |
-| **client 声明图零 Node 依赖（v0.12.0+）** | `dsh-better-sidebar/client/service` 的可达声明面（含 `Context`）不引用 `node:*` / `Buffer`——纯浏览器侧插件无需 `@types/node`，`skipLibCheck: false` 也能编译（`scripts/check-consumer-types.sh` 守护；主入口含宿主声明，宿主消费者本就处于 Node 环境） |
+| **不要 value-import `dsh-apes-sidebar`** | 即使是 `./client/service` 子路径，运行时落点也是 client bundle；只做 type-only import |
+| **client 声明图零 Node 依赖（v0.12.0+）** | `dsh-apes-sidebar/client/service` 的可达声明面（含 `Context`）不引用 `node:*` / `Buffer`——纯浏览器侧插件无需 `@types/node`，`skipLibCheck: false` 也能编译（`scripts/check-consumer-types.sh` 守护；主入口含宿主声明，宿主消费者本就处于 Node 环境） |
 | **家族右面板互斥（v0.13.0+）** | `aionui-panel` 设置的 `rightPanel` 解析为 `'aionui-panel'` 时整个侧边栏不挂载（`settings.get` 返回 `externalDisable: true`，挂载门 + 接管停用；`settings/document-updated` 推送实时生效，无 `remote` 服务回退启动时判定）。未安装 aionui 不受影响 |
 | **i18n 跟随** | 文案跟随 DSH `ctx.locale`（词典在 `betterSidebar` 命名空间；Host-backed `locale.preference` 优先于浏览器语言并实时切换；缺失回退浏览器）。消费插件**不要**依赖内部 `t()`——标题传字符串或 `() => string` |
 | **第三语言覆盖（ja 等）** | 可选 peer `@huanlin/dsh-plugin-better-locale`（optional）提供 ja/ko 覆盖，**借用 DSH 英文槽位**（仅 DSH=en 时生效，zh 下惰性）。经 `ctx.get('betterLocale')` 注入 `t()`；未安装整段 no-op |
@@ -774,12 +895,19 @@ ctx.effect(() =>
 ## 12. 皮肤兼容（令牌驱动）
 
 > better-sidebar 所有视觉值消费 DSH 的 `--dsw-alias-*` / `--dsw-font-*` / `--ds-*` 令牌（无硬编码颜色），**不做每皮肤适配**。已与 dsh-web-ui 皮肤中心兼容（10 款皮肤全覆盖 `--dsw-alias-*` 层；`tests/theme.spec.ts` 守护）。你的 tab/viewer 组件遵循同样的令牌规则即可自动兼容全部皮肤。
+>
+> **没有任何豁免面**：文件与文件夹图标是 **DSH 官方的 `FileTypeIcon` 图形**（宿主自己
+> 的调色板，插件不画像素也不存数据），插件画的每个 glyph（含内置 tab 的彩色图标）颜色
+> 都来自 `--dsw-alias-*`——`tests/theme.spec.ts` 同时守护「图标模块零颜色字面量」与
+> 「样式表里每条 `color` 都解析到令牌」。插件自己注册的图标（`registerFileIcon`）颜色由
+> 注册方负责，不受本节令牌约束，但**不要**把彩色图标数据塞进核心 bundle 的常驻渲染路径
+> （要按需加载就照 `src/client/chunk-loader.ts` 的懒加载 chunk 走）。
 
 ### 12.1 规则
 
 - **面板表面**：右/底面板背景 = `var(--dsw-alias-bg-layer-1)`。**绝不消费 `--dsw-specific-sidebar-fill`**（宿主左导航专属，皮肤按左导航语义覆盖它，面板消费会失去填充）。换面板表面 = 覆写 `--dsw-alias-bg-layer-1`。
 - **终端/编辑器表面**：`effectiveTokenValue` 读 `--dsw-alias-bg-base`——`transparent` 与 alpha < 0.9 的半透明值回退不透明底色（文字不叠背景画，issue #90）；≥ 0.9 放行。
-- **根锚点**：宿主 div 带 `data-dsh-better-sidebar`（append 到 body）；其内**面板宿主层** `[data-dsh-panel-host]`（`fixed; inset:0; z-25; pointer-events:none; overflow:hidden+clip`，v0.13.1+），面板/开关簇 absolute 定位，免疫中间层 transform 劫持；页面级 transform 触发 `data-dsh-panel-host-degraded` 降级。`overflow` 级联是**契约**（`hidden` 兜底 + `clip` 收尾，`tests/panel-host-css.spec.ts` 守护）：`hidden` 盒子仍是滚动容器，脚本滚动或浏览器 scroll-into-view 修正（焦点移入视口外区域、嵌套 iframe/工作台加载时抢焦点、面板滑出动画中 focus() 落点）会沿最近可滚祖先滚走整层——面板与开关簇集体偏离视口角（computed left/right 仍"正确"，偏移藏在盒子自身 scroll offset 里）；`clip` 裁剪语义相同但不产生滚动盒，任何路径都滚不动这层。皮肤作用域覆盖限定在 `[data-dsh-better-sidebar]` 内。
+- **根锚点**：宿主 div 带 `data-dsh-apes-sidebar`（append 到 body）；其内**面板宿主层** `[data-dsh-panel-host]`（`fixed; inset:0; z-25; pointer-events:none; overflow:hidden+clip`，v0.13.1+），面板/开关簇 absolute 定位，免疫中间层 transform 劫持；页面级 transform 触发 `data-dsh-panel-host-degraded` 降级。`overflow` 级联是**契约**（`hidden` 兜底 + `clip` 收尾，`tests/panel-host-css.spec.ts` 守护）：`hidden` 盒子仍是滚动容器，脚本滚动或浏览器 scroll-into-view 修正（焦点移入视口外区域、嵌套 iframe/工作台加载时抢焦点、面板滑出动画中 focus() 落点）会沿最近可滚祖先滚走整层——面板与开关簇集体偏离视口角（computed left/right 仍"正确"，偏移藏在盒子自身 scroll offset 里）；`clip` 裁剪语义相同但不产生滚动盒，任何路径都滚不动这层。皮肤作用域覆盖限定在 `[data-dsh-apes-sidebar]` 内。
 - **布局变量**（`<html>` 上，面板打开时有效）：`--dsh-sidebar-width` / `--dsh-sidebar-height`。右面板宽度 = AppFrame 的 `padding-right` 预留（新版 `#root [data-dsh-frame]` / rc.8 `#root > [data-slot="root"] > div` 双锚点），AppFrame border box 保持完整桌面视口宽度（Harness 以此判定桌面/窄屏布局，避免插件面板展开误入窄屏）；AppFrame 的 details 拖拽手柄按同一变量向左平移贴合列边缘。底部面板仍走 centerCol `margin-bottom`；centerCol 锚点 = **JS 标注**（禁止 `nth-child`）：侧栏 shell 的定位器给测得的 centerCol 节点打 `[data-dsh-center-col]` 标签（`Sidebar.tsx` locate，节点更换/HMR 时随 ref 迁移），`layout.css` 用 `#root [data-dsh-center-col]` 选中（`drag-layout.e2e.ts` 断言恰一节点且为对话槽宿主的父级——alpha.2 起 shell 把 `#root [data-slot="main.conversation"]` 解析进列并跳过 `display: contents` 祖先（`center-column.ts` 的 `CENTER_COLUMN_SELECTOR` 同时认 `main.conversation` 与 alpha.1 的 `conversation`），定位器从槽宿主向上取第一个非 `contents` 的祖先；frame 宽度与桌面 Session Log 由 `desktop-layout.e2e.ts` 断言）。
 - **桌面信号与标题栏**（v0.14.1+ 四方案模型 `SidebarPrefs.titleBarScheme`，唯一决策点 `src/client/titlebar-strip.ts` 纯函数）：
   - 壳信号（只读，不自动触发修改）：URL `dsh-desktop-mode` / `dsh-desktop-platform` / 可选 `dsh-desktop-titlebar-inset`（0–120 clamp）。
@@ -792,7 +920,7 @@ ctx.effect(() =>
 
 ### 12.2 注意事项
 
-- 类名是 CSS Modules 哈希，**不是契约**；精确命中用 `[data-dsh-better-sidebar]` + 子串类名（`[class*='panel']`）或 DOM 结构。
+- 类名是 CSS Modules 哈希，**不是契约**；精确命中用 `[data-dsh-apes-sidebar]` + 子串类名（`[class*='panel']`）或 DOM 结构。
 - 改动本契约必须同步本文档、设计文档与 `tests/theme.spec.ts`。
 
 ---
@@ -814,11 +942,11 @@ ctx.effect(() =>
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "dsh-better-sidebar": "workspace:*",
+    "dsh-apes-sidebar": "workspace:*",
     "react": "^18.2.0"
   },
   "peerDependenciesMeta": {
-    "dsh-better-sidebar": { "optional": true }
+    "dsh-apes-sidebar": { "optional": true }
   }
 }
 ```
@@ -827,7 +955,7 @@ ctx.effect(() =>
 
 ```tsx
 import { createElement } from 'react'
-import type {} from 'dsh-better-sidebar'  // 触发 ctx.betterSidebar 类型合并
+import type {} from 'dsh-apes-sidebar'  // 触发 ctx.betterSidebar 类型合并
 import type { Context } from '@deepseek-ai/cordis'
 
 export const inject = ['betterSidebar']
@@ -905,7 +1033,7 @@ better-sidebar 的内置 tab 和 viewer 就是参考实现（"吃狗粮"），
 
 - **接入方式**：可选软依赖——client half 本地重述最小服务契约（`registerTab`），未安装 better-sidebar 时注册静默跳过，插件原有表面不受影响；
 - **注册内容**：`dsh-sentinel:watches` tab（order 60，单实例）：全服务器监控表 + 最近触发历史；
-- **类型处理**：未 value-import `dsh-better-sidebar`，构建零耦合；与 §2 的 `import type {}` 方案可互换；
+- **类型处理**：未 value-import `dsh-apes-sidebar`，构建零耦合；与 §2 的 `import type {}` 方案可互换；
 - **实测**：v0.3.0 起，真实 web profile 验证通过。
 
 通过 `ctx.betterSidebar` 的三方插件 [dsh-sidebar-qa](https://github.com/ChenRuoT/dsh-sidebar-qa) —— 基于 better-sidebar 的划选提问：对话划选 → 右侧面板提问 → 同工作区独立追问会话（❓追问·主题）；快速无思考模型压缩主对话上下文后与引文一起注入，不打断主对话；追问可嵌套、可继续、可归档。

docs/plans/2026-09-09-dsh-0.1.5-alpha.2-adaptation.md

@@ -17,6 +17,10 @@ DSH `dsh-v0.1.5-alpha.1..dsh-v0.1.5-alpha.2` 的宿主契约里有一批会实
 | 5 | `ui-sidebar-textpreview` 被 `ui-sidebar-documentpreview` 取代（同 `text` kind、`fallback` 带、`dsh-resource://file/**` 模式） | 插件 `editor` 仍以 `extension` 优先级认领 `dsh-resource://file/**`，压过其 `text` 的 `fallback` 带 |
 | 6 | 基线升到 0.1.5-alpha.2（peer 下限 / manifest / CI 钉版） | 插件基线 = alpha.2 only；alpha.1 用户留在 v0.19.0-alpha.0 |
 
+> 后续（2026-09-10）：`SidebarRightGuideEntry.description` 在 DSH 0.1.5-rc.1 回归（可选，且宿主只在 guide 列出的条目 ≤ 4 条时渲染），插件已在 **v0.19.0** 恢复该字段——见 [2026-09-10-dsh-0.1.5-rc.1-adaptation.md](./2026-09-10-dsh-0.1.5-rc.1-adaptation.md)。
+>
+> 后续（2026-09-10）：退役自绘右侧面板（#605）时，`use-host-feeds.ts` 的三处自动激活被误改成 `target: 'bottom'`，任务页因此落到插件自己的底部工作台而非 DSH 原生右侧栏。修复见 [2026-09-10-auto-activation-native-landing-fix.md](./2026-09-10-auto-activation-native-landing-fix.md)。
+
 ## 决策
 
 - **基线 = alpha.2 only**：peer 下限 `^0.1.5-alpha.2`、manifest `>=0.1.5-alpha.2`、CI 钉 `@deepseek-ai/dsh@0.1.5-alpha.2`；不再对 alpha.1 做运行时兼容。
@@ -78,3 +82,9 @@ DSH `dsh-v0.1.5-alpha.1..dsh-v0.1.5-alpha.2` 的宿主契约里有一批会实
 - 不接入 alpha.2 全局面板（`main` 槽 / `sidebar.panellist` / `ctx.layout` / `usePanelInfo` / 根级 `rightbar`）。
 - 不引入 `subagent/catalog` 读取面。
 - 不改 DSH 源码（仓库硬约束 §1）。
+
+## 落地
+
+- #603 → #604 → #605 → #609 依序合入 `main`（各自 retarget 到 main 后以 merge commit 合并）；main 的 `package.json` 为 `0.19.0-alpha.1`、`engines.dsh` 为 `>=0.1.5-alpha.2`。main 的 CI 首轮 `ci-windows` 因既有的 pty/git 5s 超时抖动失败，重跑后三 job 全绿。
+- 发布 [v0.19.0-alpha.1](https://github.com/omdsh-dev/DSH-better-sidebar/releases/tag/v0.19.0-alpha.1)：`release.yml` 通过全门禁后经 npm Trusted Publishing 发布，npm `alpha` dist-tag → `0.19.0-alpha.1`（带 provenance）。发布产物核对：`lib/index.js` 与本地已验证构建逐字节一致；`lib/client.js` 仅差打包非确定性（已知）；`package.json` 仅少 dev-only 字段（`packageManager` / `prepare` / `prepublishOnly`，npm 发布时剥离）。
+- 注意：新版本在 registry 上可见有约 5 分钟传播延迟（版本元数据先到、tarball 后到），期间 `npm view`/tarball 可能 404——不是发布失败。

docs/plans/2026-09-09-terminal-wait-banner-design.md

@@ -0,0 +1,192 @@
+# 终端等待 banner（wait banner + 跳过）设计
+
+> 2026-09-09 · 目标 v0.18.2
+
+## 背景
+
+`terminal_wait_for`（v0.18.1，PR #595 起 needle 支持 regex）会阻塞 agent 的工具调用直到
+needle 出现 / 超时 / 终端退出。等待期间用户在侧边栏看不到任何"agent 正在等什么"的信号，
+也无法干预——只能等 agent 自己超时（默认 10s，长等待可设到分钟级）。
+
+需求：
+
+1. agent 开始 `wait for needle` 时，在对应终端的顶部显示 banner：
+   **「Agent 正在等待 {needle}」**，右侧「跳过等待」按钮；
+2. 点击跳过后，`terminal_wait_for` 立即返回，agent 明确知道是用户跳过（而非超时）；
+3. 终端 tab 未激活时也能感知等待 → tab 标题加 ⏳ 徽章。
+
+## 方案对比
+
+| 方案 | 思路 | 取舍 |
+|---|---|---|
+| **A. 搭现有推送车（采纳）** | 等待状态并入 `AgentTerminalSnapshot`，经现有 `/sidebar/ws/agent-terminals` 推送；跳过走新 `/sidebar/api` 方法 | 改动集中；零新 WS 生命周期；推送时机由 registry `notify()` 天然覆盖 |
+| B. 独立 waits 推送 WS | 新开 `/sidebar/ws/agent-waits` | 重连/订阅/teardown 全套翻倍，YAGNI |
+| C. 客户端轮询 | 定时拉 terminal 列表 | 延迟与开销差，违背现有推送架构 |
+
+已确认的两个决策：
+
+- **skip 语义 = 新增第四种返回 `kind:'skipped'`**（不复用 timeout、不走 abort——abort
+  语义属于工具调用取消，用户语义只是"不等了"）；
+- **banner 主体在终端卡片顶部 + tab 标题 ⏳ 徽章**（复用 v0.12+ 的 `TabDescriptor.badge`
+  通道，git tab 有先例）。
+
+## 设计
+
+### 1. Host：`AgentPtyRegistry`（src/agent-pty.ts）
+
+- `AgentTerminalHandle` 增活动等待记录数组 `waits: Array<{ needle, since, skipped }>`；
+  并发 `wait_for` 同 uuid 时各登记一条。
+- `waitFor()`：快速路径（已 exited / needle 已在 transcript）不登记、不推 banner；
+  进入轮询前登记记录并 `notify()`（banner 出现），`finally` 移除记录并 `notify()`（banner
+  消失——found/timeout/exited/skipped/工具 abort 五条出路统一走 finally）。
+- 轮询每圈检查本记录的 `skipped` → 返回 `{ kind:'skipped', needle }`；50ms 轮询
+  天然承载跳过延迟，无需事件唤醒。与终端退出在同一 tick 竞争时**退出优先**（见实施
+  偏差记录）。
+- 新方法 `skipWait(uuid): number`：标记该 uuid 全部活动记录并返回条数；uuid 未知 →
+  `not-found` 404（与 `expect` 一致）。
+- `AgentTerminalSnapshot` 增 `waiting?: { needle: string; since: number }`（取最新登记
+  的一条；并发等待显示最新 needle，跳过跳过全部）。
+- `AgentTerminalWaitResult` 增 `skipped` 变体。
+
+### 2. 工具层：`terminal_wait_for`（src/tools.ts）
+
+- output schema `oneOf` 增 `{ kind: 'skipped', needle }` 分支；
+- render：`Skipped by user while waiting for "<needle>" — the wait ended early; call terminal_read to inspect the transcript if needed.`；
+- 工具描述补一句：用户可从侧栏 banner 跳过等待（返回 `skipped`）。
+
+### 3. API：`buildApi`（src/index.ts）
+
+- 新方法 `'agent-pty.skip-wait'`（命名对齐现有 `'agent-pty.close'`）：
+  `requireString uuid` → `registry.skipWait(uuid)`；degraded 模式（registry 为 null）
+  幂等返回 `{ ok: true, skipped: 0 }`。
+
+### 4. 推送零改动
+
+`attachAgentList` 发的就是 `registry.list(sessionId)`，snapshot 新增的 `waiting` 字段
+自动随车；等待开始/结束由 `notify()` 触发推送。兼容性：
+
+- 旧客户端 + 新 host：多余字段被忽略；
+- 新客户端 + 旧 host：永远收不到 `waiting` → 无 banner，安全降级。
+
+### 5. 客户端状态（src/client/state.ts）
+
+- `SidebarState` 增 `agentWaits: Record<uuid, { needle: string; since: number }>`（默认
+  `{}`；等待结束即删除键）；
+- `reconcileAgentTerminals` 从同一推送同步该映射——需解除"无 tab 增删即早退"的短路
+  （仅 waiting 变化也要产出新状态）；
+- **不持久化**：`sanitizeState` 逐字段重建、不恢复该字段 → 刷新后自然清空；WS attach
+  即发首条推送，立刻纠正。
+
+### 6. Banner（src/client/TerminalView.tsx）
+
+- 仅 `agent:` tab 渲染；位置在终端区顶部（现有 fatal/deps banner 之上）；
+- 内容：`t('terminalWaitBanner', { needle })`（zh「Agent 正在等待 {needle}」）+ 右侧
+  `t('terminalSkipWait')`（zh「跳过等待」）按钮 → `api.agentSkipWait(uuid)`；
+- needle 超 ~80 字符截断显示，`title` 悬浮显全文；
+- banner 消失完全由推送驱动（skipped/exited/abort 均经 `notify`），点击不做乐观更新。
+
+### 7. Tab ⏳ 徽章（src/client/builtins/tabs.tsx）
+
+- terminal 描述符增 `badge: (_ctx, scope, state) => ...`：`agent:` tab 且
+  `state.agentWaits[uuid]` 存在时返回 `'⏳'`，否则 null——复用 v0.12+ 徽章通道
+  （git changes tab 先例），不碰 `TabBar`。
+
+### 8. i18n / 样式
+
+- 词典键：`terminalWaitBanner`、`terminalSkipWait`；zh/en 同步，**ja 翻译必须同步
+  `src/client/locales-ja.ts`**（仓库规则）；
+- `.terminalWaitBanner` 全部消费 `--dsw-alias-*` / `--ds-*` 令牌，无硬编码颜色
+  （皮肤契约，`tests/theme.spec.ts` 守护）。
+
+### 9. 测试
+
+- `tests/agent-pty.spec.ts`：跳过返回 `skipped`；活动等待期间 snapshot 含 `waiting`、
+  结束后消失；`skipWait` 未知 uuid → 404、无活动等待 → 0；等待开始/结束触发 `notify`；
+- `tests/tools.spec.ts`：FakeRegistry 增 skipped 形状；schema/render 断言；
+- `tests/agent-terminal-reconcile.spec.ts`：`agentWaits` 设置/清除、仅 waiting 变化也
+  触发状态更新；
+- badge / banner 组件测试视现有 jsdom 基建可行性补齐。
+
+## 边缘情况
+
+- **并发多个 `wait_for` 同一 uuid**：banner/⏳ 显示最新登记的 needle；跳过一次跳过全部；
+- **工具调用取消（abort）**：`finally` 移除记录 → banner 消失并推送；
+- **终端退出 / 用户关 tab（close frame 杀 pty）**：轮询下一圈返回 `exited`，记录移除；
+- **UI-tab 终端**：无等待概念，`agentWaits` 永不含有其条目。
+
+## 不做的事
+
+- 不新增独立 waits WebSocket（方案 B 否决）；
+- 不改 `ctx.betterSidebar` 服务面（`external-plugin-guide.md` 无需同步）；
+- 不做乐观 UI（banner 消失以服务端推送为准）。
+
+## 实施偏差记录
+
+- **⏳ tab 徽章不走 `TabDescriptor.badge`**：实现时核实该 API 是 type-keyed
+  （`badge(ctx, scope, state)`，无 tab 参数、external 插件共享），无法定位单个
+  tab。改为 Sidebar 壳层 `tabBadgeOf` 的 sidebar-internal 特例（agent: 前缀判断
+  + `state.agentWaits` 查表），`service.ts` 与 external-plugin-guide.md 零改动。
+- **banner 抽为独立组件 `TerminalWaitBanner.tsx`**：设计原文写在 TerminalView
+  内；抽出后无 xterm 依赖，jsdom 单测可直接渲染（TerminalView 仍负责订阅 store
+  并把 onSkip 接到 `api.agentSkipWait`）。
+- **词典同步扩到全部 21 个语言文件**：设计只写了 zh/en/ja，但
+  `tests/locales.spec.ts` 断言每个第三方词典与 zh 键集相等——只同步三语会让该
+  守护测试挂掉。按仓库惯例（全语言同步，如 e8761ee）补齐其余 18 语言同两键。
+- **banner 配色**：仓库 CSS 无 state-info 令牌，沿用 `.terminalBanner` 的 warn
+  对（`--dsw-alias-state-warn-label/-tertiary`），符合皮肤契约。
+- **设计文档与计划随 feat 分支进 PR**：main 受分支保护，纯文档直推被 hook 拒绝
+  （`4a6a77a` / `2448068` 随本分支合并）。
+- **测试断言以文本计数取代 CSS 类名**：CSS module 类名在测试变换下不稳定，
+  ⏳ 数量断言改从 `textContent` 计数；长 needle 截断断言改为计量 needle 自身
+  贡献字符数（本地化句子包裹 needle，整体长度断言与语言相关，原计划内部矛盾）。
+- **新测试的 localStorage 兜底**：Node 26 + jsdom 29 组合下测试环境可能无全局
+  `localStorage`（上游 `bottom-auto-terminal.spec.tsx` 在同环境即失败，属已知
+  win32/环境非回归类）；新 spec 的 afterEach 加守卫 + try/catch（jsdom opaque
+  origin 下 localStorage 可以是 throwing accessor，裸 typeof 也会炸），
+  上游测试一律未动。
+- **已知限制：跨会话 pinned 虚拟 tab 收不到实时 banner/⏳**（Copilot review
+  指出）：等待状态 feed 按 viewer 会话订阅（`/sidebar/ws/agent-terminals` 按
+  当前 sessionId 连接），钉到其他会话的 pinned 虚拟 agent tab
+  （`pinned:<homeSessionId>:agent:<uuid>`）在其 home 会话非当前会话时收不到
+  实时等待状态。修复需跨会话 wait feed 多路复用（连 home 会话推送或聚合
+  推送），超出本特性范围，留待后续设计；跳过 API 按 uuid 全局寻址，跨会话
+  跳过本身可达。
+- **Copilot review 第三轮修复（合并 rc.1 后扫描）**：
+  1. `truncateNeedle` 改按 Unicode 码点截断（`Array.from`），原 UTF-16 码元
+     截断会在截断点劈开代理对（emoji 渲染为替换字符）；
+  2. banner 消息加 `role="status"` + `aria-live="polite"`，完整未截断的
+     本地化消息经 `aria-label` 提供给读屏器（不新增词典键）；
+  3. `terminal` tab 类型禁用时推送处理从整体跳过改为 `mirrorAgentWaits`
+     ——仍镜像权威 `waiting` map（等在禁用窗口内 resolve 也清 banner 状态），
+     只跳过 tab 增删 reconcile，否则重启用后已开终端残留 stale banner/⏳
+     直到无关推送到达；
+  4. badge 测试跟踪挂载的 root 并在 `afterEach` 里先 unmount 再清 DOM
+     （裸 `innerHTML = ''` 不触发 React effect 清理，store 订阅/host-feed
+     effect 会泄漏进后续测试）；
+  5. 补并发双 `waitFor` 同 uuid 测试：快照显示最新 needle（`waits.at(-1)`）、
+     `skipWait` 返回 2、两个 promise 都以各自 needle `skipped` 收敛、快照
+     清空且 skipWait 幂等归零。
+- **轮询优先级：终端退出优先于用户跳过**（v0.19.0 发版前 review 发现）：设计原文
+  写「每圈优先检查 `skipped`」，实现是 `aborted → handle.exited → record.skipped`，
+  即 pty 退出与用户点跳过落进同一个 50ms tick 时返回 `exited`。**维持实现现状**，
+  设计原文已同步为「退出优先」：两种顺序下用户可见结果完全相同（banner 消失、
+  `skipWait` 返回 0、等待结束），只有工具结果的 `kind` 文案不同；而进程已死是
+  客观事实，报 `exited` 不撒谎，工具结果本身也引导 agent 用 `terminal_read` 复核。
+  若日后要让「用户意图优先」，改动点是循环内两行先后 + 一条同 tick 竞态测试。
+- **两个已知限制的补充记录**（同一次 review）：
+  1. **pinned tab 的 banner 与 ⏳ 不对称**：pinned 虚拟 id 是
+     `pinned:<homeSessionId>:agent:<uuid>`，`isAgentTabId` 只认 `agent:` 前缀，因此
+     钉住的 agent tab **不会误挂 ⏳**（比"收不到"更强的保证）；但 Workbench 渲染
+     pinned tab 时给 TerminalView 传的是**原 tab id + home 作用域**，所以 home 会话
+     正在等待时该视图**会**显示 banner，而它的 strip 徽章仍不出现。两个信号数据源
+     不同（banner 读 home store，徽章读 viewer 的 `agentWaits`）。
+  2. **⏳ 到不了 DSH 原生右侧栏**：徽章经 `getTabBadge` 渲染，唯一消费点是插件
+     自绘的 `TabBar`；原生栏的 `NativeTabTitle` 契约只带 title，不带 badge。agent
+     终端标签页走 `openTabInBottomPane`（底部工作台），故 agent 流程可见；这是原生
+     承载面契约决定的上限，非本特性缺陷。
+- **注释随实现同步**（v0.19.0 发版前 review）：`use-host-feeds.ts` effect 头部原写
+  「terminal tab 类型禁用时 pushes are ignored」，与上面第 3 项的 `mirrorAgentWaits`
+  改法矛盾，已改为「不增删 tab，但仍镜像权威 wait map」；`src/index.ts` 的
+  `agent-pty.skip-wait` 注释原文把「无活动等待 → 0」泛化成了「幂等」，已收窄为
+  「无活动等待返回 `{skipped:0}`；未知 uuid 走 `expect` → 404（已退出的终端即属此
+  列），客户端 `.catch` 容忍并等下一次推送收敛」。

docs/plans/2026-09-09-terminal-wait-banner-plan.md

@@ -0,0 +1,980 @@
+# 终端等待 banner + 跳过等待 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** agent 阻塞在 `terminal_wait_for` 时，对应终端卡片顶部显示「Agent 正在等待 {needle}」banner（右侧「跳过等待」按钮），tab 标题加 ⏳ 徽章；跳过后工具返回新增的 `{kind:'skipped'}`。
+
+**Architecture:** 等待状态登记在 `AgentPtyRegistry` 的 handle 上，随现有 `/sidebar/ws/agent-terminals` 推送快照（`waiting` 字段）自然下发；跳过走新增 `/sidebar/api/agent-pty.skip-wait` 路由。客户端把推送镜像进 `state.agentWaits`，banner 组件与 tab 徽章从 store 读。
+
+**Tech Stack:** TypeScript / React 18 / vitest（node 环境 pty 测试 + jsdom Sidebar 壳测试）/ ws 推送 / CSS Modules（皮肤令牌）。
+
+**Spec:** `docs/plans/2026-09-09-terminal-wait-banner-design.md`（与本计划同分支，执行者两份都读）。
+
+## Global Constraints
+
+- 分支：`feat/wait-banner`（已含设计文档提交 `4a6a77a`）；所有代码改动走该分支 → PR，禁止直推 main（分支保护）。
+- 皮肤契约：新增 CSS 只允许 `--dsw-alias-*` / `--dsw-font-*` / `--ds-*` 令牌；本项目复用现成 warn 对 `--dsw-alias-state-warn-label` / `--dsw-alias-state-warn-tertiary`（仓库 CSS 无 state-info 令牌，已核实）。
+- i18n：新增 zh key 必须同步 en 词典与 `src/client/locales-ja.ts` 的 ja 翻译。
+- client bundle 纯度门：新文件只准 import 本插件模块（locales / css / api），禁止 value-import `@dsh-external/*` 或非白名单 `@deepseek-ai/*`。
+- 不改 `src/client/service.ts` / `docs/external-plugin-guide.md`（⏳ 徽章走 shell 层特例，不动 TabDescriptor API）。
+- 上游测试（含 win32 已知 27 个非回归失败）一律不改。
+- 每个任务用 `pnpm exec vitest run <file>` 验证；最终任务必须 `pnpm lint` + `pnpm typecheck` + `pnpm test` + `pnpm build` 全绿才 push（CI 曾因漏 lint 挂过）。
+- 提交信息风格：`feat(terminal): ...` / `test(...)`，仓库惯例小写 scope。
+
+---
+
+### Task 1: Registry 等待登记 + `skipped` 结果 + `waiting` 快照
+
+**Files:**
+- Modify: `src/agent-pty.ts`
+- Test: `tests/agent-pty.spec.ts`
+
+**Interfaces:**
+- Consumes: 现有 `AgentPtyRegistry.waitFor` / `notify` / `subscribe` / `snapshotOf`。
+- Produces:
+  - `type AgentTerminalActiveWait = { needle: string; since: number; skipped: boolean }`
+  - `AgentTerminalHandle.waits: AgentTerminalActiveWait[]`（create 时初始化为 `[]`）
+  - `AgentTerminalSnapshot.waiting?: { needle: string; since: number }`（最新一条活动等待）
+  - `AgentTerminalWaitResult` 新增 `{ kind: 'skipped'; needle: string }` 变体
+  - `registry.skipWait(uuid: string): number`（标记全部活动等待，返回条数；未知 uuid 抛 not-found）
+
+- [ ] **Step 1: 写失败测试（4 个新用例，加在 `describe('AgentPtyRegistry')` 内、现有 `waitFor` 用例之后）**
+
+在 `tests/agent-pty.spec.ts` 的 import 块不需要新增（`AgentPtyRegistry` / `snapshotOf` 已导入）。追加用例：
+
+```ts
+  it('waitFor returns skipped when the user skips from the sidebar', async () => {
+    const registry = new AgentPtyRegistry(testShell())
+    try {
+      const uuid = registry.create('s1', 'skip-test', 'echo skip-ready', process.cwd(), 80, 24)
+      await waitForTranscript(registry, uuid, 'skip-ready')
+      // waitFor registers its record synchronously (before the first poll
+      // await), so the skip can fire immediately after the call.
+      const waitPromise = registry.waitFor(uuid, 'NEVER_APPEARS_XYZ', 30_000)
+      expect(await registry.skipWait(uuid)).toBe(1)
+      const result = await waitPromise
+      expect(result.kind).toBe('skipped')
+      if (result.kind === 'skipped') expect(result.needle).toBe('NEVER_APPEARS_XYZ')
+      // Idempotent: nothing left to skip once the wait resolved.
+      expect(registry.skipWait(uuid)).toBe(0)
+    } finally {
+      registry.disposeAll()
+    }
+  })
+
+  it('snapshot exposes waiting while a wait is active and clears after it ends', async () => {
+    const registry = new AgentPtyRegistry(testShell())
+    try {
+      const uuid = registry.create('s1', 'wait-snap', 'echo snap-ready', process.cwd(), 80, 24)
+      await waitForTranscript(registry, uuid, 'snap-ready')
+      const waitPromise = registry.waitFor(uuid, 'LATER_MARK_9', 30_000)
+      // Registration happens synchronously before waitFor's first await.
+      expect(registry.list('s1')[0]?.waiting?.needle).toBe('LATER_MARK_9')
+      expect(typeof registry.list('s1')[0]?.waiting?.since).toBe('number')
+      expect(registry.skipWait(uuid)).toBe(1)
+      const result = await waitPromise
+      expect(result.kind).toBe('skipped')
+      expect(registry.list('s1')[0]?.waiting).toBeUndefined()
+    } finally {
+      registry.disposeAll()
+    }
+  })
+
+  it('fires change listeners when a wait starts and ends', async () => {
+    const registry = new AgentPtyRegistry(testShell())
+    try {
+      const uuid = registry.create('s1', 'watched-wait', 'echo notify-ready', process.cwd(), 80, 24)
+      await waitForTranscript(registry, uuid, 'notify-ready')
+      let changes = 0
+      const unsubscribe = registry.subscribe(() => { changes += 1 })
+      const waitPromise = registry.waitFor(uuid, 'NEVER_NOTIFY_1', 30_000)
+      const afterStart = changes
+      expect(afterStart).toBeGreaterThanOrEqual(1)
+      expect(await registry.skipWait(uuid)).toBe(1)
+      expect(await waitPromise).toEqual({ kind: 'skipped', needle: 'NEVER_NOTIFY_1' })
+      expect(changes).toBeGreaterThan(afterStart)
+      unsubscribe()
+    } finally {
+      registry.disposeAll()
+    }
+  })
+
+  it('skipWait rejects an unknown uuid with not-found', () => {
+    const registry = new AgentPtyRegistry(testShell())
+    try {
+      expect(() => registry.skipWait('missing-uuid')).toThrow(/not found/)
+    } finally {
+      registry.disposeAll()
+    }
+  })
+```
+
+- [ ] **Step 2: 跑测试确认失败**
+
+Run: `pnpm exec vitest run tests/agent-pty.spec.ts`
+Expected: FAIL — `waiting` 为 undefined、`skipWait` 不存在、skipped 分支不存在（TS 编译错误或断言失败）。
+
+- [ ] **Step 3: 实现 `src/agent-pty.ts`**
+
+(a) 在 `AgentTerminalReadResult` 之后、`AgentTerminalWaitResult` 之前新增：
+
+```ts
+/** One active wait_for registration on a handle (banner + skip bookkeeping). */
+export interface AgentTerminalActiveWait {
+  /** The needle being awaited (shown on the sidebar wait banner). */
+  needle: string
+  /** Epoch ms when the wait registered (age display / debugging). */
+  since: number
+  /** Flipped by `skipWait()`; the waiting poll returns `skipped` within one tick. */
+  skipped: boolean
+}
+```
+
+(b) `AgentTerminalWaitResult` union 末尾追加变体：
+
+```ts
+  | {
+    /** The user skipped the wait from the sidebar banner. */
+    kind: 'skipped'
+    /** The needle that was awaited. */
+    needle: string
+  }
+```
+
+(c) `AgentTerminalSnapshot` 追加字段（`exitSignal` 之后）：
+
+```ts
+  /**
+   * The model's active `terminal_wait_for` on this terminal (the sidebar
+   * renders the wait banner from it). Present only while a wait is
+   * registered; carries the LATEST wait when several overlap.
+   */
+  waiting?: { needle: string; since: number }
+```
+
+(d) `AgentTerminalHandle` 追加字段（`exitSignal` 之后）：
+
+```ts
+  /** Active wait_for registrations (skip bookkeeping; empty while idle). */
+  waits: AgentTerminalActiveWait[]
+```
+
+(e) `create()` 的 handle 字面量中 `exited: false,` 之后加 `waits: [],`。
+
+(f) `snapshotOf` 在 `return out` 前追加：
+
+```ts
+  const active = handle.waits.at(-1)
+  if (active !== undefined) out.waiting = { needle: active.needle, since: active.since }
+```
+
+(g) 新方法（放在 `waitFor` 之后）：
+
+```ts
+  /**
+   * Mark every active wait on one terminal as skipped (the sidebar banner's
+   * skip button). Each waiting poll loop observes its record's flag within
+   * one 50ms tick and returns `{kind:'skipped'}`. Idempotent: 0 when nothing
+   * is waiting (a stale banner racing a wait that already resolved).
+   * @returns the number of waits that transitioned to skipped.
+   */
+  skipWait(uuid: string): number {
+    const handle = this.expect(uuid)
+    let count = 0
+    for (const record of handle.waits) {
+      if (!record.skipped) {
+        record.skipped = true
+        count += 1
+      }
+    }
+    return count
+  }
+```
+
+(h) 重写 `waitFor` 中段（`const firstHit = ...` 快速路径之后到方法结尾），登记记录 + 轮询检查 + `finally` 清理：
+
+```ts
+    const firstHit = locateNeedle(handle.transcript, needle, re)
+    if (firstHit !== undefined) {
+      return { kind: 'found', needle, line: firstHit.line, column: firstHit.column, match: firstHit.match, elapsedMs: Date.now() - start }
+    }
+    // Register the active wait so the sidebar can show the wait banner (the
+    // snapshot's `waiting` field rides the agent-terminals push). Registered
+    // only after the fast paths: a wait that resolves instantly never
+    // flashes the banner. The notify() makes every push subscriber (the
+    // sidebar view) converge on the new waiting state immediately.
+    const record: AgentTerminalActiveWait = { needle, since: start, skipped: false }
+    handle.waits.push(record)
+    this.notify()
+    try {
+      while (true) {
+        if (signal?.aborted) signal.throwIfAborted()
+        if (handle.exited) {
+          return { kind: 'exited', needle, exitCode: handle.exitCode ?? null, exitSignal: signalNameOf(handle.exitSignal) }
+        }
+        if (record.skipped) {
+          return { kind: 'skipped', needle }
+        }
+        const hit = locateNeedle(handle.transcript, needle, re)
+        if (hit !== undefined) {
+          return { kind: 'found', needle, line: hit.line, column: hit.column, match: hit.match, elapsedMs: Date.now() - start }
+        }
+        if (Date.now() >= deadline) {
+          return { kind: 'timeout', needle, timeoutMs: timeout, totalLines: handle.transcript.split('\n').length }
+        }
+        await new Promise(resolve => {
+          const t = setTimeout(resolve, 50)
+          // Allow the Node process to exit even if the timer is pending.
+          if (typeof t === 'object' && 'unref' in t) (t as { unref: () => void }).unref()
+        })
+      }
+    } finally {
+      const index = handle.waits.indexOf(record)
+      if (index !== -1) handle.waits.splice(index, 1)
+      this.notify()
+    }
+```
+
+(i) `waitFor` 的 JSDoc：`@returns one of `found` / `timeout` / `exited`.` 改为 `@returns one of `found` / `timeout` / `exited` / `skipped`.`；并在 `@param signal` 行后补一行 `* A wait can also be skipped by the user from the sidebar banner (`skipWait`), which resolves it with `{kind:'skipped'}`.`
+
+- [ ] **Step 4: 跑测试确认通过**
+
+Run: `pnpm exec vitest run tests/agent-pty.spec.ts`
+Expected: PASS（全部用例，含既有 425 行文件内的用例）。
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/agent-pty.ts tests/agent-pty.spec.ts
+git commit -m "feat(terminal): registry 支持等待登记、skipWait 与 skipped 结果"
+```
+
+---
+
+### Task 2: 工具层 `skipped` 分支 + 宿主 `agent-pty.skip-wait` 路由
+
+**Files:**
+- Modify: `src/tools.ts`（terminal_wait_for 定义，约 287-377 行）
+- Modify: `src/index.ts`（buildApi 表，`'agent-pty.close'` 之后，约 545 行）
+- Test: `tests/tools.spec.ts`
+
+**Interfaces:**
+- Consumes: Task 1 的 `AgentTerminalWaitResult` skipped 变体、`registry.skipWait(uuid): number`。
+- Produces: `/sidebar/api/agent-pty.skip-wait` 路由（payload `{uuid}` → `{ok:true, skipped:number}`）；工具 output schema 第四分支；Task 4 的客户端 `api.agentSkipWait` 调它。
+
+- [ ] **Step 1: 写失败测试**
+
+`tests/tools.spec.ts`：(a) `FakeRegistry` 增加注入口 —— 在 `readonly terminals = ...` 行后加属性，并把 `waitFor` 改为：
+
+```ts
+  /** When set, waitFor resolves with the skipped shape instead of the found default. */
+  nextWaitResult: { kind: 'skipped' } | undefined
+
+  waitFor(_uuid: string, needle: string): Promise<
+    { kind: 'found'; needle: string; line: number; column: number; match: string; elapsedMs: number }
+    | { kind: 'skipped'; needle: string }
+  > {
+    // Mirrors the registry's empty-needle rejection (the tool layer no
+    // longer duplicates this check).
+    if (needle === '') return Promise.reject(new Error('needle must be a non-empty string'))
+    if (this.nextWaitResult !== undefined) return Promise.resolve({ kind: 'skipped', needle })
+    return Promise.resolve({ kind: 'found', needle, line: 0, column: 0, match: needle, elapsedMs: 1 })
+  }
+```
+
+(b) 在 `describe('agent terminal tools')` 内、现有 `terminal_wait_for returns the registry result...` 用例后追加：
+
+```ts
+  it('terminal_wait_for returns skipped (schema-valid) when the registry reports a user skip', async () => {
+    const { captured, registry } = mount()
+    const tool = toolOf(captured, 'terminal_wait_for')
+    registry.nextWaitResult = { kind: 'skipped' }
+    const value = await tool.execute({ uuid: 'uuid-1', needle: 'BUILD_OK', timeout_ms: 1000 }, exec('s1'))
+    expect(value).toEqual({ kind: 'skipped', needle: 'BUILD_OK' })
+    expect(validateJsonSchemaValue(tool.output.schema, value, 'value')).toEqual([])
+  })
+
+  it('terminal_wait_for render describes the user skip and the needle', () => {
+    const { captured } = mount()
+    const tool = toolOf(captured, 'terminal_wait_for')
+    const blocks = tool.output.render({}, { kind: 'skipped', needle: 'BUILD_OK' }) as Array<{ type: string; text: string }>
+    expect(blocks[0]!.type).toBe('text')
+    expect(blocks[0]!.text).toContain('Skipped by user')
+    expect(blocks[0]!.text).toContain('BUILD_OK')
+  })
+```
+
+- [ ] **Step 2: 跑测试确认失败**
+
+Run: `pnpm exec vitest run tests/tools.spec.ts`
+Expected: FAIL（schema 拒绝 skipped / render 走到 exited 分支输出不符）。
+
+- [ ] **Step 3: 实现**
+
+(a) `src/tools.ts` terminal_wait_for：
+
+描述末尾（`'The wait is cooperative: ...'` 句之后）追加一句：
+
+```ts
+      + 'The user can skip the wait from the sidebar ( a banner on the terminal\'s tab shows the needle and a skip button ) — the tool then returns `skipped`.',
+```
+
+output.schema 的 `oneOf` 数组末尾（exited 分支对象之后）追加：
+
+```ts
+          {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              kind: { type: 'string', required: true, const: 'skipped' },
+              needle: { type: 'string', required: true },
+            },
+          },
+```
+
+render 的 value 类型与分支 —— `const v = value as { kind: 'found' | 'timeout' | 'exited' | 'skipped'; ... }`（原行加 `'skipped'`），并在 timeout 分支后插入：
+
+```ts
+        if (v.kind === 'skipped') {
+          return [{ type: 'text', text: `Skipped by user while waiting for "${v.needle}" — the wait ended early. Call terminal_read to inspect the transcript and decide how to proceed.` }]
+        }
+```
+
+(b) `src/index.ts` buildApi 表，`'agent-pty.close'` 条目（约 541-545 行）之后追加：
+
+```ts
+    // The sidebar wait banner's skip button: abort every active
+    // terminal_wait_for on one agent terminal. Idempotent — 0 when nothing
+    // is waiting (a stale banner racing a wait that already resolved).
+    // Degraded mode (node-pty unavailable) has no registry and no waits: an
+    // honest ok.
+    'agent-pty.skip-wait': (payload) => {
+      const uuid = requireString(payload, 'uuid')
+      return { ok: true, skipped: agentPtyRegistry?.skipWait(uuid) ?? 0 }
+    },
+```
+
+- [ ] **Step 4: 跑测试确认通过**
+
+Run: `pnpm exec vitest run tests/tools.spec.ts`
+Expected: PASS。
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/tools.ts src/index.ts tests/tools.spec.ts
+git commit -m "feat(terminal): terminal_wait_for 增 skipped 结果与 agent-pty.skip-wait 路由"
+```
+
+---
+
+### Task 3: 客户端状态 `agentWaits` 镜像 + 推送类型
+
+**Files:**
+- Modify: `src/client/state.ts`（SidebarState 接口 ~121 行、makeDefaultState ~221 行、sanitizeState ~1283 行、reconcileAgentTerminals ~1017 行）
+- Modify: `src/client/sidebar/use-host-feeds.ts`（~66 行解析类型）
+- Test: `tests/agent-terminal-reconcile.spec.ts`
+
+**Interfaces:**
+- Consumes: 宿主推送数组（Task 1 的 snapshot 含 `waiting`）。
+- Produces:
+  - `SidebarState.agentWaits: Record<string, { needle: string; since: number }>`（uuid → 活动等待；瞬态，不持久化）
+  - `reconcileAgentTerminals(state, list)` 的 list 元素增 `waiting?: { needle: string; since: number } | null`，并把等待状态镜像进 `agentWaits`（仅等待变化也产出新状态）。
+
+- [ ] **Step 1: 写失败测试**
+
+`tests/agent-terminal-reconcile.spec.ts` 追加两个用例（沿用文件现有 import，无需新增）：
+
+```ts
+  it('mirrors the pushed waiting state into agentWaits and clears it when it ends', () => {
+    let s = makeDefaultState()
+    s = reconcileAgentTerminals(s, [{ uuid: 'aaa-111', title: 'busy', waiting: { needle: 'READY_1', since: 42 } }])
+    expect(s.agentWaits['aaa-111']).toEqual({ needle: 'READY_1', since: 42 })
+    // The next push without waiting drops the entry (the push is authoritative).
+    s = reconcileAgentTerminals(s, [{ uuid: 'aaa-111', title: 'stable' }])
+    expect(s.agentWaits['aaa-111']).toBeUndefined()
+  })
+
+  it('produces a new state when ONLY the wait state changes (no tab add/remove)', () => {
+    let s = makeDefaultState()
+    s = reconcileAgentTerminals(s, [{ uuid: 'aaa-111', title: 'stable' }])
+    const before = s
+    const next = reconcileAgentTerminals(s, [{ uuid: 'aaa-111', title: 'stable', waiting: { needle: 'N', since: 1 } }])
+    expect(next).not.toBe(before)
+    expect(next.agentWaits['aaa-111']).toBeDefined()
+    // Idempotent: the same push again returns the same reference.
+    expect(reconcileAgentTerminals(next, [{ uuid: 'aaa-111', title: 'stable', waiting: { needle: 'N', since: 1 } }])).toBe(next)
+  })
+```
+
+- [ ] **Step 2: 跑测试确认失败**
+
+Run: `pnpm exec vitest run tests/agent-terminal-reconcile.spec.ts`
+Expected: FAIL（`agentWaits` 不存在 → TS 错误 / 断言失败）。
+
+- [ ] **Step 3: 实现**
+
+(a) `SidebarState` 接口 `floats: FloatWindow[]` 之后追加：
+
+```ts
+  /**
+   * Live agent-terminal wait state (uuid → the wait the model currently
+   * blocks on in `terminal_wait_for`), mirrored from the host's
+   * agent-terminals push. Transient by design: sanitizeState never restores
+   * it, so a reload starts clean and the next push (sent immediately on WS
+   * attach) repopulates it.
+   */
+  agentWaits: Record<string, { needle: string; since: number }>
+```
+
+(b) `makeDefaultState` 的返回字面量 `floats: [],` 之后加 `agentWaits: {},`。
+
+(c) `sanitizeState` 的返回字面量 `floats,` 之后加（带注释）：
+
+```ts
+    // The agent wait state is TRANSIENT (like revealed): never restored from
+    // storage — the host's first push after attach repopulates it.
+    agentWaits: {},
+```
+
+(d) `reconcileAgentTerminals`：参数类型改为
+
+```ts
+  agentTerminals: ReadonlyArray<{ uuid: string; title: string; waiting?: { needle: string; since: number } | null }>,
+```
+
+在 `const toRemove = ...` 之后、`if (toAdd.length === 0 && toRemove.length === 0) return state` 处，替换为：
+
+```ts
+  // Mirror the live wait state from the push (authoritative: a vanished
+  // waiting field simply drops the entry). A waits-only change must still
+  // produce a new state — the tab add/remove no-change check alone would
+  // swallow banner updates.
+  const serverWaits: Record<string, { needle: string; since: number }> = {}
+  for (const terminal of agentTerminals) {
+    if (terminal.waiting !== undefined && terminal.waiting !== null) {
+      serverWaits[terminal.uuid] = { needle: terminal.waiting.needle, since: terminal.waiting.since }
+    }
+  }
+  if (toAdd.length === 0 && toRemove.length === 0 && sameAgentWaits(state.agentWaits, serverWaits)) return state
+```
+
+文件末尾的 `return next` 改为 `return { ...next, agentWaits: serverWaits }`。
+
+在 `reconcileAgentTerminals` 前方新增辅助函数：
+
+```ts
+/** Shallow equality of two agent-wait maps (same keys, same needle+since). */
+function sameAgentWaits(
+  a: SidebarState['agentWaits'] | undefined,
+  b: Record<string, { needle: string; since: number }>,
+): boolean {
+  if (a === undefined) return Object.keys(b).length === 0
+  const aKeys = Object.keys(a)
+  if (aKeys.length !== Object.keys(b).length) return false
+  for (const key of aKeys) {
+    const av = a[key]
+    const bv = b[key]
+    if (av === undefined || bv === undefined) return false
+    if (av.needle !== bv.needle || av.since !== bv.since) return false
+  }
+  return true
+}
+```
+
+(e) `src/client/sidebar/use-host-feeds.ts` 66 行的解析类型改为：
+
+```ts
+          const list = JSON.parse(event.data) as Array<{ uuid: string; title: string; command: string; exited: boolean; waiting?: { needle: string; since: number } | null }>
+```
+
+- [ ] **Step 4: 跑测试确认通过 + 全仓 typecheck（状态字段新增会暴露遗漏的构造点）**
+
+Run: `pnpm exec vitest run tests/agent-terminal-reconcile.spec.ts && pnpm typecheck`
+Expected: PASS。若 typecheck 报其他 `SidebarState` 字面量缺 `agentWaits`（tests 里的手搓状态），补 `agentWaits: {}` —— **只许改测试里测试自己构造的字面量，不许改上游断言逻辑**。
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/client/state.ts src/client/sidebar/use-host-feeds.ts tests/agent-terminal-reconcile.spec.ts
+git commit -m "feat(sidebar): 镜像 agent 终端等待状态到 agentWaits（瞬态）"
+```
+
+---
+
+### Task 4: 等待 banner 组件 + TerminalView 接线 + api 方法 + i18n + CSS
+
+**Files:**
+- Create: `src/client/TerminalWaitBanner.tsx`
+- Modify: `src/client/TerminalView.tsx`（render 区 ~387-408 行 + 组件顶部订阅）
+- Modify: `src/client/api.ts`（`agentPtyClose` 之后 ~348 行）
+- Modify: `src/client/locales.ts`（zh ~117 / en ~567，紧随 `terminalRetry`）
+- Modify: `src/client/locales-ja.ts`（~105，紧随 `terminalRetry`）
+- Modify: `src/client/sidebar.module.css`（`.terminalBanner` 块之后 ~2202 行）
+- Test: `tests/terminal-wait-banner.spec.tsx`（新建）
+
+**Interfaces:**
+- Consumes: Task 2 的 `agent-pty.skip-wait` 路由；Task 3 的 `state.agentWaits`；`api` 对象、`t()`、`css` module。
+- Produces: `TerminalWaitBanner({ needle: string; onSkip: () => void })` + `truncateNeedle(needle: string): string`（80 字符截断）；词典键 `terminalWaitBanner` / `terminalSkipWait`。
+
+- [ ] **Step 1: 写失败测试（新文件 `tests/terminal-wait-banner.spec.tsx`）**
+
+```tsx
+/**
+ * TerminalWaitBanner unit tests: localized text with the needle, the skip
+ * button wiring, and the long-needle display cap (full text stays on the
+ * title attribute). The component imports no xterm — renderable in plain
+ * jsdom (the repo's jsdom pattern, see bottom-auto-terminal.spec.tsx head).
+ */
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest'
+import { createElement } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { act } from 'react-dom/test-utils'
+import { setupReactAct } from './test-utils.ts'
+setupReactAct()
+
+import { TerminalWaitBanner } from '../src/client/TerminalWaitBanner.tsx'
+
+describe('TerminalWaitBanner', () => {
+  const mounted: Array<{ root: Root; container: HTMLDivElement }> = []
+  function mount(needle: string, onSkip: () => void): HTMLDivElement {
+    const container = document.createElement('div')
+    document.body.append(container)
+    const root = createRoot(container)
+    act(() => { root.render(createElement(TerminalWaitBanner, { needle, onSkip })) })
+    mounted.push({ root, container })
+    return container
+  }
+  afterEach(() => {
+    for (const { root, container } of mounted.splice(0)) {
+      act(() => { root.unmount() })
+      container.remove()
+    }
+  })
+
+  it('shows the localized waiting text with the needle and a working skip button', () => {
+    let skipped = 0
+    const container = mount('BUILD_OK', () => { skipped += 1 })
+    // jsdom navigator.language is en-US → the en dictionary applies.
+    expect(container.textContent).toContain('Agent is waiting for')
+    expect(container.textContent).toContain('BUILD_OK')
+    expect(container.textContent).toContain('Skip wait')
+    const button = container.querySelector('button')
+    expect(button).not.toBeNull()
+    act(() => { button!.dispatchEvent(new MouseEvent('click', { bubbles: true })) })
+    expect(skipped).toBe(1)
+  })
+
+  it('truncates a long needle for display but keeps the full text on the title', () => {
+    const long = 'X'.repeat(200)
+    const container = mount(long, () => {})
+    const span = container.querySelector('span[title]')
+    expect(span).not.toBeNull()
+    expect(span!.getAttribute('title')).toBe(long)
+    expect((span!.textContent ?? '').length).toBeLessThanOrEqual(80)
+  })
+})
+```
+
+- [ ] **Step 2: 跑测试确认失败**
+
+Run: `pnpm exec vitest run tests/terminal-wait-banner.spec.tsx`
+Expected: FAIL（模块不存在）。
+
+- [ ] **Step 3: 实现**
+
+(a) 新建 `src/client/TerminalWaitBanner.tsx`：
+
+```tsx
+/**
+ * The "Agent 正在等待 {needle}" wait banner: rendered at the top of an
+ * agent-owned terminal's view while the model blocks in terminal_wait_for.
+ * The skip button asks the host to abort every active wait on the terminal
+ * (`agent-pty.skip-wait`); the banner disappears when the host's next
+ * agent-terminals push drops the waiting field — no optimistic UI. Kept in
+ * its own module (no xterm imports) so jsdom tests can render it directly.
+ */
+import { t } from './locales.ts'
+import css from './sidebar.module.css'
+
+/** Cap the needle shown inline; the full text rides the title tooltip. */
+const NEEDLE_DISPLAY_CAP = 80
+
+/** Truncate one needle for inline display (title attr carries the full text). */
+export function truncateNeedle(needle: string): string {
+  return needle.length > NEEDLE_DISPLAY_CAP ? `${needle.slice(0, NEEDLE_DISPLAY_CAP - 1)}…` : needle
+}
+
+export function TerminalWaitBanner(props: { needle: string; onSkip: () => void }) {
+  const { needle, onSkip } = props
+  return (
+    <div className={css.terminalWaitBanner}>
+      <span className={css.terminalWaitNeedle} title={needle}>
+        {t('terminalWaitBanner', { needle: truncateNeedle(needle) })}
+      </span>
+      <button type="button" className={css.terminalRetry} onClick={onSkip}>
+        {t('terminalSkipWait')}
+      </button>
+    </div>
+  )
+}
+```
+
+(b) `src/client/api.ts`：`agentPtyClose` 条目之后追加：
+
+```ts
+  /** Skip every active terminal_wait_for on one agent terminal (the wait
+   *  banner's skip button). Idempotent: {skipped:0} when none is active. */
+  agentSkipWait: (uuid: string) =>
+    call<{ ok: true; skipped: number }>('agent-pty.skip-wait', { uuid }),
+```
+
+(c) `src/client/locales.ts`：zh 词典 `terminalRetry: '重试',` 行后加：
+
+```ts
+  terminalWaitBanner: 'Agent 正在等待 {needle}',
+  terminalSkipWait: '跳过等待',
+```
+
+en 词典 `terminalRetry: 'Retry',` 行后加：
+
+```ts
+  terminalWaitBanner: 'Agent is waiting for {needle}',
+  terminalSkipWait: 'Skip wait',
+```
+
+(d) `src/client/locales-ja.ts`：`terminalRetry: '再試行',` 行后加（仓库规则：新 zh 键必须同步 ja）：
+
+```ts
+  terminalWaitBanner: 'エージェントが {needle} を待機中',
+  terminalSkipWait: '待機をスキップ',
+```
+
+(e) `src/client/sidebar.module.css`：`.terminalBannerUrl` 块之后加：
+
+```css
+/* The "Agent 正在等待 {needle}" wait banner: a warn-toned strip above the
+   terminal surface while the model blocks in terminal_wait_for; the needle
+   ellipsizes inline and the full text rides the title tooltip. */
+.terminalWaitBanner {
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 3px 10px;
+  font: var(--dsw-font-xxxs-11);
+  color: var(--dsw-alias-state-warn-label);
+  background: var(--dsw-alias-state-warn-tertiary);
+}
+
+.terminalWaitNeedle {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+```
+
+(f) `src/client/TerminalView.tsx`：
+
+imports 区追加：
+
+```ts
+import { TerminalWaitBanner } from './TerminalWaitBanner.tsx'
+```
+
+组件体内（`const [lastUrl, setLastUrl] = ...` 之后）加等待订阅：
+
+```ts
+  // Agent terminals only: the model's active terminal_wait_for (mirrored
+  // from the host's agent-terminals push into the store) drives the wait
+  // banner. Read + subscribe like the font prefs above; the banner vanishes
+  // when the host's push drops the waiting field (skip / exit / abort all
+  // converge through the same push). getSnapshot() is {sessionId, state?,
+  // prefs} — the state may be briefly undefined around session switches.
+  const agentUuid = isAgentTabId(tabId) ? agentUuidOf(tabId) : null
+  const [waiting, setWaiting] = useState<{ needle: string; since: number } | undefined>(undefined)
+  useEffect(() => {
+    if (agentUuid === null) return
+    const read = (): void => {
+      const next = store.getSnapshot().state?.agentWaits?.[agentUuid]
+      setWaiting(prev => {
+        const nextValue = next === undefined ? undefined : { needle: next.needle, since: next.since }
+        if (prev?.needle === nextValue?.needle && prev?.since === nextValue?.since) return prev
+        return nextValue
+      })
+    }
+    read()
+    return store.subscribe(read)
+  }, [agentUuid, store])
+```
+
+return JSX 中 `<div className={css.terminalWrap}>` 的第一个子元素位置（`depsFatal` 条目之前）加：
+
+```tsx
+      {agentUuid !== null && waiting !== undefined && (
+        <TerminalWaitBanner
+          needle={waiting.needle}
+          onSkip={() => { void api.agentSkipWait(agentUuid).catch(() => { /* 跳过失败时 banner 留存，可重试 */ }) }}
+        />
+      )}
+```
+
+- [ ] **Step 4: 跑测试确认通过**
+
+Run: `pnpm exec vitest run tests/terminal-wait-banner.spec.tsx`
+Expected: PASS。
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/client/TerminalWaitBanner.tsx src/client/TerminalView.tsx src/client/api.ts src/client/locales.ts src/client/locales-ja.ts src/client/sidebar.module.css tests/terminal-wait-banner.spec.tsx
+git commit -m "feat(sidebar): agent 终端等待 banner（needle + 跳过等待按钮）"
+```
+
+---
+
+### Task 5: tab 标题 ⏳ 徽章（shell 层特例）+ jsdom 链路测试
+
+**Files:**
+- Modify: `src/client/Sidebar.tsx`（`tabBadgeOf` ~828-841 行）
+- Test: `tests/agent-wait-badge.spec.tsx`（新文件，harness 照抄 `tests/bottom-auto-terminal.spec.tsx` 1-97 行的模式）
+
+**Interfaces:**
+- Consumes: Task 3 的 `state.agentWaits`；`isAgentTabId` / `agentUuidOf`（Sidebar.tsx 已 import，第 38-39 行）。
+- Produces: agent tab 的 ⏳ 徽章 pill（复用 `css.tabBadge`）；推送 → 状态 → 徽章全链路。
+
+- [ ] **Step 1: 写失败测试（新文件 `tests/agent-wait-badge.spec.tsx`）**
+
+完整文件（FakeWebSocket 记录 url 与实例，驱动 `/sidebar/ws/agent-terminals` 推送；`registerStubTerminal` 防止懒加载 chunk 在 jsdom 里拉真实 bundle）：
+
+```tsx
+/**
+ * The agent-terminal wait badge chain, end to end in jsdom: the host's
+ * agent-terminals push (mirroring the real /sidebar/ws/agent-terminals
+ * frames) reconciles tabs AND the wait map; the shell's tabBadgeOf renders
+ * the hourglass pill on the agent tab while a wait is live and drops it
+ * when the push clears. Harness mirrors tests/bottom-auto-terminal.spec.tsx
+ * (real Sidebar shell + fake context + stubbed WebSocket).
+ */
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createElement } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { act } from 'react-dom/test-utils'
+import { setupReactAct } from './test-utils.ts'
+setupReactAct()
+
+import { Sidebar } from '../src/client/Sidebar.tsx'
+import { createSidebarStore, openTabInActivePane } from '../src/client/state.ts'
+import { createBetterSidebarService, type BetterSidebarService } from '../src/client/service.ts'
+
+/** jsdom has no WebSocket; the agent-terminals push effect constructs one on mount. */
+class FakeWebSocket {
+  static instances: FakeWebSocket[] = []
+  onmessage: ((event: { data: unknown }) => void) | null = null
+  onclose: (() => void) | null = null
+  onerror: (() => void) | null = null
+  close = (): void => {}
+  constructor(readonly url: string) {
+    FakeWebSocket.instances.push(this)
+  }
+}
+
+let sessionSeq = 0
+
+function mountSidebar(): { container: HTMLDivElement; store: ReturnType<typeof createSidebarStore>; service: BetterSidebarService; unmount: () => void } {
+  vi.stubGlobal('WebSocket', FakeWebSocket)
+  FakeWebSocket.instances = []
+  const container = document.createElement('div')
+  document.body.append(container)
+  const store = createSidebarStore()
+  const service = createBetterSidebarService(store)
+  // Replace the terminal descriptor with a stub: the real one lazy-loads the
+  // xterm chunk, which jsdom cannot fetch — the badge under test renders in
+  // the TAB STRIP, independent of the view component.
+  service.registerTab({
+    id: 'terminal',
+    title: () => 'Terminal',
+    component: () => null,
+  })
+  const sessionId = `s1-${++sessionSeq}`
+  store.setSession(sessionId)
+  // Stub the terminal descriptor: the real one lazy-loads the xterm chunk,
+  // which jsdom cannot fetch (the bottom-auto-terminal harness does the same).
+  service.registerTab({
+    id: 'terminal',
+    title: () => 'Terminal',
+    component: () => null,
+  })
+  const localeSnapshot = { active: 'en' }
+  const sessionsSnapshot = {
+    current: sessionId,
+    byId: { [sessionId]: { cwd: '/tmp' } },
+  }
+  const ctx = {
+    locale: { subscribe: () => () => {}, getSnapshot: () => localeSnapshot },
+    sessions: { list: { subscribe: () => () => {}, getSnapshot: () => sessionsSnapshot } },
+    betterSidebar: service,
+    get: (name: string) => name === 'betterSidebar' ? service : undefined,
+  }
+  const root: Root = createRoot(container)
+  act(() => { root.render(createElement(Sidebar, { ctx: ctx as never, store })) })
+  return {
+    container,
+    store,
+    service,
+    unmount: () => {
+      act(() => { root.unmount() })
+      container.remove()
+    },
+  }
+}
+
+let sessionSeq = 0
+
+afterEach(() => {
+  document.body.innerHTML = ''
+  localStorage.clear()
+  vi.unstubAllGlobals()
+})
+
+/** The agent-terminals push socket the shell opened for the current session. */
+function feedsSocket(): FakeWebSocket {
+  const socket = FakeWebSocket.instances.find(candidate => candidate.url.includes('/sidebar/ws/agent-terminals'))
+  if (socket === undefined) throw new Error('agent-terminals socket not connected')
+  return socket
+}
+
+describe('agent terminal wait badge (push → state → tab pill)', () => {
+  it('shows ⏳ on the agent tab while a wait is active and drops it when it ends', () => {
+    const { container } = mountSidebar()
+    const terminal = { uuid: 'u1', title: 'dev server', command: '', exited: false }
+    // First push: the agent tab lands in the active pane.
+    act(() => { feedsSocket().onmessage?.({ data: JSON.stringify([terminal]) }) })
+    expect(container.textContent).toContain('dev server')
+    expect(container.textContent).not.toContain('⏳')
+    // Second push carries a live wait → the hourglass pill appears.
+    act(() => { feedsSocket().onmessage?.({ data: JSON.stringify([{ ...terminal, waiting: { needle: 'READY_1', since: 1 } }]) }) })
+    expect(container.textContent).toContain('⏳')
+    // The wait resolved (skip/exit/abort all converge to a waiting-less push).
+    act(() => { feedsSocket().onmessage?.({ data: JSON.stringify([terminal]) }) })
+    expect(container.textContent).not.toContain('⏳')
+  })
+
+  it('shows ⏳ only on agent tabs, never on UI-owned terminal tabs', () => {
+    const { container, store } = mountSidebar()
+    // A UI-owned terminal tab (id NOT agent:) lives in the strip too; the
+    // badge lookup keys on the agent uuid, so it never badges.
+    act(() => { store.reduce(s => openTabInActivePane(s, { id: 'terminal:manual-1', type: 'terminal', title: 'UI terminal' })) })
+    const terminal = { uuid: 'u1', title: 'dev server', command: '', exited: false }
+    act(() => { feedsSocket().onmessage?.({ data: JSON.stringify([{ ...terminal, waiting: { needle: 'READY_1', since: 1 } }]) }) })
+    // Exactly ONE hourglass: the agent tab. (Counted from textContent — CSS
+    // module class names are not stable under the test transform.)
+    expect((container.textContent.match(/⏳/g) ?? []).length).toBe(1)
+    // The wait resolved → the pill disappears entirely.
+    act(() => { feedsSocket().onmessage?.({ data: JSON.stringify([terminal]) }) })
+    expect(container.textContent).not.toContain('⏳')
+  })
+})
+```
+
+> 实现注意：`sessionSeq` 声明放 `mountSidebar` 之前（与 bottom-auto-terminal.spec.tsx 相同的模块级写法）；`createSidebarStore` 返回类型直接用 `ReturnType<typeof createSidebarStore>`，勿手写接口。
+
+- [ ] **Step 2: 跑测试确认失败**
+
+Run: `pnpm exec vitest run tests/agent-wait-badge.spec.tsx`
+Expected: FAIL（⏳ 从不出现）。
+
+- [ ] **Step 3: 实现 Sidebar.tsx 的 `tabBadgeOf` 特例**
+
+`src/client/Sidebar.tsx` 828 行 `const tabBadgeOf = (tab: SidebarTab): ReactNode => {` 函数体开头（descriptor 查找之前）插入：
+
+```ts
+    // Agent-terminal wait indicator (sidebar-internal, deliberately NOT a
+    // TabDescriptor.badge — that API is type-keyed and shared with external
+    // plugins, and cannot address one tab): the agent-terminals push mirrors
+    // the model's live terminal_wait_for into state.agentWaits; an agent tab
+    // whose uuid is waiting shows the hourglass pill.
+    if (isAgentTabId(tab.id)) {
+      const wait = state.agentWaits?.[agentUuidOf(tab.id)]
+      if (wait !== undefined) return <span className={css.tabBadge}>{'⏳'}</span>
+    }
+```
+
+（`isAgentTabId` / `agentUuidOf` 已在 38-39 行 import；`css` / `state` 均在作用域内。）
+
+- [ ] **Step 4: 跑测试确认通过**
+
+Run: `pnpm exec vitest run tests/agent-wait-badge.spec.tsx`
+Expected: PASS（2 个用例）。
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/client/Sidebar.tsx tests/agent-wait-badge.spec.tsx
+git commit -m "feat(sidebar): agent 终端 tab 标题在等待时显示 ⏳ 徽章"
+```
+
+---
+
+### Task 6: 设计文档偏差记录 + 全量验证 + 推送 + PR
+
+**Files:**
+- Modify: `docs/plans/2026-09-09-terminal-wait-banner-design.md`（实施偏差记录节）
+- 无代码改动。
+
+- [ ] **Step 1: 更新设计文档**
+
+在 `docs/plans/2026-09-09-terminal-wait-banner-design.md` 末尾追加：
+
+```markdown
+
+## 实施偏差记录
+
+- **⏳ tab 徽章不走 `TabDescriptor.badge`**：实现时核实该 API 是 type-keyed
+  （`badge(ctx, scope, state)`，无 tab 参数，external 插件共享），无法定位单个
+  tab。改为 Sidebar 壳层 `tabBadgeOf` 的 sidebar-internal 特例（agent: tab 前缀
+  判断 + `state.agentWaits` 查表），`service.ts` 与 external-plugin-guide.md
+  零改动。
+- **banner 抽为独立组件 `TerminalWaitBanner.tsx`**：设计原文写在
+  TerminalView.tsx 内；抽出后无 xterm 依赖，可直接被 jsdom 单测渲染
+  （TerminalView 仍负责订阅 store 并接线 onSkip → api.agentSkipWait）。
+- **设计文档随 feat 分支进 PR**：main 受分支保护，纯文档直推被 hook 拒绝
+  （`4a6a77a` 随本分支合并）。
+- **banner 配色**：仓库 CSS 无 state-info 令牌，沿用 `.terminalBanner` 的
+  warn 对（`--dsw-alias-state-warn-label/-tertiary`），符合皮肤契约。
+```
+
+- [ ] **Step 2: 全量验证**
+
+Run（依次，全绿才继续）：
+`pnpm lint` → `pnpm typecheck` → `pnpm test` → `pnpm build`
+
+Expected:
+- lint: 0 error（历史上 CI 因 no-useless-assignment 挂过——新代码避免「先声明后必然覆盖」的写法）；
+- test: 除已知的 win32 非回归失败集（bottom-auto-terminal / free-window / sidebar-auto-activation / sidebar-crash 等既有失败，对照 main 基线）外全绿，新增 spec 全部 PASS；
+- build: lib/ 产物含新 chunk `client.js` 变化（TerminalWaitBanner 打进 client bundle）。
+
+- [ ] **Step 3: 提交并推送**
+
+```bash
+git add docs/plans/2026-09-09-terminal-wait-banner-design.md
+git commit -m "docs(plans): 终端等待 banner 实施偏差记录"
+git push -u origin feat/wait-banner
+```
+
+- [ ] **Step 4: 建 PR**
+
+```bash
+gh pr create --repo omdsh-dev/DSH-better-sidebar --base main --head feat/wait-banner \
+  --title "feat(terminal): 等待 banner + 跳过等待（terminal_wait_for skipped）" \
+  --body "设计：docs/plans/2026-09-09-terminal-wait-banner-design.md（随本 PR）。agent 阻塞在 terminal_wait_for 时：对应终端卡片顶部显示「Agent 正在等待 {needle}」banner，右侧跳过按钮走 agent-pty.skip-wait；tab 标题 ⏳ 徽章；工具新增 {kind:'skipped'} 返回。"
+```
+
+- [ ] **Step 5: 等待 CI（用 terminal_wait_for 盯 `(ci|ci-windows|plugin-mount).*\((pass|fail)\)` 之类的多结局 needle，勿 sleep）**
+
+Expected: 三个 job 全 pass。

docs/plans/2026-09-10-auto-activation-native-landing-fix.md

@@ -0,0 +1,60 @@
+# 自动激活落点修复：任务页回到 DSH 原生右侧栏
+
+日期：2026-09-10　分支：`fix/auto-activation-native-landing`
+
+## 背景
+
+用户报告：**自动打开的侧边栏是底栏，而不是右侧边栏**。两个自动激活开关（`autoOpenSubagent` / `autoOpenJobs`）与子代理拓扑跳回在 v0.19.0 上把任务页（`subagent` tab）开进了插件自绘的**底部工作台**，底栏随之展开；而产品文案描述的是侧边栏落点——README 特性表「新子代理 / 新任务可自动激活任务页，**宽屏同时展开侧边栏**，窄屏不强制展开全屏抽屉」，`settingsSubagentDesc` / `settingsJobsDesc` 及全部 20 份词典同样措辞，README 的 #314 条目也写着「宽屏展开侧边栏，窄屏只准备 Tab」。
+
+## 根因
+
+`223b254`（v0.19.0-alpha.0「退役插件自绘右侧面板与自由窗口」）改写了 `src/client/sidebar/use-host-feeds.ts` 的三处触发：
+
+| | 改动前（v0.18.x） | 改动后（v0.19.0） |
+|---|---|---|
+| 展开 | `store.reduce(s => s.panelOpen ? s : togglePanel(s))`（宽屏才展开） | 无（由落点决定） |
+| 落点 | `activePane = firstLeaf(s.splits).id` + `openTab({ type:'subagent', title })` —— **无 `target`** | `openTab({ type:'subagent', title, target:'bottom' })` |
+
+`service.ts:683` 的判据是「装了原生面 + 非 `bottom` → 落 DSH 原生右侧栏」，`target: 'bottom'` 直接绕过它走 `land = openTabInBottomPane`（`service.ts:744` → `state.ts:453`，置 `bottomOpen: true`）。也就是说：退役右侧面板时，`splits`（插件自己的右面板）消失，落点被改成了插件自己的**底**面板，而正解是当时同文件其它打开早已默认落上的新宿主——DSH 原生右侧栏。
+
+## 决策
+
+| # | 决策 | 理由 |
+|---|---|---|
+| 1 | 三处触发改回默认落点（`'right'`） | 宿主 `openContent` 内部 `planSetExpanded(state, true)`（`dsh-client-ui-sidebar-right`），打开即在同一步展开原生栏；这才是文案里的「侧边栏」 |
+| 2 | 后台活动（子代理 / 新任务）在窄屏**停放**，不展开 | 宿主 `RightbarSeat` 有 `autoFullscreen = viewportWidth < 768`，该宽度下原生栏以 `position: fixed; inset: 0` 全屏绘制——展开即整屏抢占，正是 #373 修掉的行为。宿主没有「只放 tab、不展开」的公开选项，故开前读 `ctx.sidebarRight.isExpanded()`、开后 `toggleExpanded()` 收回；两次提交落在同一 React 批内，中间态不会渲染 |
+| 3 | 停放仅在目标会话在屏时执行 | `isExpanded` / `toggleExpanded` 作用于**已挂载会话**（`mounted()` = `binding.surfaces[binding.sessionId]`）；目标不在屏时执行会误动用户当前那一栏 |
+| 4 | 拓扑跳回（用户点击）一律展开 | 它是显式手势，不是后台活动；对齐 v0.18.x 跳回无窄屏门禁的语义 |
+| 5 | 底部工作台自有流程保持 `target: 'bottom'` | 底栏 `+` 菜单（`Sidebar.tsx:628`）与首次展开自动终端（`:336`）本就该落底栏；`OpenTabSeed.target` API 不变 |
+
+阈值一致性：插件既有 `NARROW_MAX_WIDTH = 768`（`width < 768`，`src/client/breakpoints.ts`）与宿主 `viewportWidth < 768` 的全屏规则逐字对齐，不引入第二个断点。
+
+窄屏语义与 v0.18.x 等价：**tab 已就位、抽屉不展开**（用户点开会话头右侧的展开控件即可看到任务页）。
+
+## 改动清单（子系统级）
+
+| 子系统 | 文件 | 变更 |
+|---|---|---|
+| 触发 | `src/client/sidebar/use-host-feeds.ts` | 新增模块内 `activateTasksPage(ctx, sessionId, { background })`（落点 + 停放判定集中在此）；三处调用改为它（子代理 / 后台任务 `background: true`，跳回 `false`）；重新引入 `isNarrowWidth`；三段 docblock 与文件头同步 |
+| 测试 | `tests/sidebar-auto-activation.spec.tsx` | 断言原生面收到 `openTab { kind:'subagent', revealIfOpened:true }`、底部工作台保持原状（未展开、未新增 tab）、窄屏停放次数（1 / 0）、宽屏与已展开栏不停放、去抖触发时读视口、跳回不停放 |
+
+无 API / 持久化 / i18n / README 行为文案改动：文案本就在描述修复后的行为。
+
+## 验证
+
+- **回归守护（确定性）**：新 spec 10 passed；把 `src/client/sidebar/use-host-feeds.ts` 回退到 `HEAD` 后同 10 条**全红**（10 failed），证明它测的正是这次修复。
+- **门槛**：`pnpm typecheck` / `pnpm lint` / `pnpm check:consumer-types` 干净；`pnpm test` = **124 files / 1299 passed / 9 skipped**（较基线 +3 条，即本 spec 的净增）。
+- **打包挂载**：`pnpm build && pnpm pack && pnpm test:mount` = **7 passed**（真实 DSH 0.1.5-rc.1，scratch profile，不触碰用户 `~/.dsh`）。
+- **环境事实（踩过一次）**：本机 PATH 上的 `dsh` 是 **0.1.2-rc.1**，用它跑挂载车道会在 `dsh plugin add` 后报 `dsh-better-sidebar 未出现在 dsh.profile.bundles 中——挂载未注册`（该版本不会把 `file:` tarball 注册进 profile bundles，且插件 peer 要求 `^0.1.5-rc.1`）。CI 装的是钉版 0.1.5-rc.1；本地需用同版本的 shim / `DSH_CMD` 才能复现车道结果。
+- **真机**：见 PR 描述（3080 实例，web profile 换装新 tarball 后人工触发子代理 / 后台任务确认）。
+
+## 未覆盖（诚实记录）
+
+- 挂载车道是 keyless 的（无模型），无法真派生子代理或后台任务，因此**该行为只有单测是确定性证据**；宿主 `session/create` 的请求体不接受 `origin` / `parentId`，也无法用 RPC 造出 `origin: 'subagent'` 的子会话，所以真机断言只能依赖人工触发或非确定性的 prompt。
+- 宿主若在窄屏自行折叠（`shown && !fullscreen && !canShow` 的 room rule），停放不会与之冲突（两者都指向「不展开」）。
+
+## 不做
+
+- 不新增设置项、不改变 `OpenTabSeed.target` 的语义、不把任务页改到别处承载。
+- 不动底栏 `+` 菜单 / 首次展开自动终端（它们是底部工作台自己的流程）。
+- 不改 DSH 源码（仓库硬约束 §1）。

docs/plans/2026-09-10-dsh-0.1.5-rc.1-adaptation.md

@@ -0,0 +1,86 @@
+# DSH 0.1.5-rc.1 适配（v0.19.0 正式版基线）
+
+日期：2026-09-10　分支：`feat/dsh-0.1.5-rc.1`
+
+## 背景
+
+DSH `dsh-v0.1.5-alpha.2..dsh-v0.1.5-rc.1`（上游 commit `183f08e9c`，npm 发布 2026-09-10T03:12Z）的 delta 很小：373 个变更文件，绝大多数是各包 `package.json` 版本号、原生右侧栏预览 UI 打磨与测试快照。触及本插件的只有一处契约回归——`SidebarRightGuideEntry.description` 回来了。本计划记录该 delta、插件对它的取舍、以及 v0.19.0 正式版的基线决策。上一版（alpha.2）的适配记录见 [2026-09-09-dsh-0.1.5-alpha.2-adaptation.md](./2026-09-09-dsh-0.1.5-alpha.2-adaptation.md)；插件对外的全部行为差异以 [docs/external-plugin-guide.md](../external-plugin-guide.md) 为准；仓库级适配要点（基线、CI 钉版、宿主契约）同步到 [AGENTS.md](../AGENTS.md) §2/§3。
+
+## 上游 delta（alpha.2 → rc.1，影响本插件的三项）
+
+| # | 上游变更 | 对插件的影响 |
+|---|---|---|
+| 1 | `SidebarRightGuideEntry.description?: () => string` 回归（可选）：原生指南**只在列出条目 ≤ 4 条时**渲染它（上游 `MAX_DESCRIBED_ENTRIES = 4`），更长的列表整列丢弃说明；没有 `icon` 的条目改由宿主补方块占位 | 恢复 `TabDescriptor.description`（六个内置类型声明它，`guideDesc*` 词条一并回来）；**不恢复**旧的通用兜底句 `nativeGuideDesc`——宿主自己没有兜底，通用句在所有页面上长得一样、纯噪音；未声明该字段的 descriptor 就不发 `description` 字段 |
+| 2 | 内置 `files` 类型重新声明指南说明，且改用彩色的 `FileTypeIcon kind="folder"` 作指南字形 | 仅背景信息：`files` 页面 kind 由插件接管，该行现在随插件渲染（`editor` descriptor 的图标与说明） |
+| 3 | `@deepseek-ai/dsh-client-ui-primitives@0.1.5-rc.1` **仍不声明 `dependencies`**，而其 bundle 继续裸 import `anser` / `shiki` / `@shikijs/langs/*` / `mdast-util-*` / `micromark-*` / `katex` | 上一版提升进 devDependencies 的那组第三方包**不得回退**（回退即 vitest 一加载 primitives 就 `Cannot find package 'anser'`）；`ui-primitives` 的导出面未变，只有 CodeBlock 渲染变化 |
+
+**明确未变**（不必再核）：
+
+- 全局主面板模型——根级 keyed `main` 槽、`sidebar.panellist`、`ctx.layout.selectPanel` / `beginNavigation`、根级 `rightbar` + `rightbar.session`；插件仍不接入。
+- 文件地址语法——`packages/util/workspace-path` 只动了 `package.json` 的版本号。
+- 原生 tab 体宿主契约——`dsh-client-ui-dockkit` 的 `.paneBody` 仍是「有确定高度的块级滚动容器」，只加了两行 z-index。
+- core / agent / session / subagent 宿主 API——仅版本号变化。
+
+## 决策
+
+- **插件版本 0.19.0（无 prerelease 后缀）**：`release.yml` 按「版本号是否含 `-`」自动选 dist-tag，因此本版发 npm **`latest`**；npm 的 `alpha` 标签保持指向 `0.19.0-alpha.1`（上游 rc.1 自己的 GitHub Release 仍标 pre-release，与本插件的通道无关）。
+- **基线 = DSH 0.1.5-rc.1+ only**：peer 下限 `^0.1.5-rc.1`、manifest `engines.dsh >=0.1.5-rc.1`、CI 钉 `@deepseek-ai/dsh@0.1.5-rc.1`。DSH **0.1.5-alpha.2 用户留在 v0.19.0-alpha.1**，DSH **0.1.2-rc.1 用户留在 v0.18.1**。
+- **恢复 `description`，不恢复通用兜底句**：宿主渲染第二行时读 descriptor 自己的说明；`nativeGuideDesc` 兜底句不再存在——没写说明的条目就是单行「图标 + 标题」。
+- **接受 ≤4 渲染规则，不做额外工程**：插件默认贡献 6 个 guide 条目 > 4，说明在默认组合下不渲染（见下节）。不为此裁剪内置类型、不改条目数、不把关键信息只放进说明里。
+- **升级本地 3080 实例**到 DSH 0.1.5-rc.1 + 插件 0.19.0，作为真机观察点。
+
+## ≤4 渲染规则的后果（重要）
+
+上游只在 guide 列出的条目 **≤ 4 条**时渲染 `description`（`MAX_DESCRIBED_ENTRIES = 4`），更长的列表整列丢掉所有说明——注意是「整列丢弃」，不是截断到前四条。插件默认贡献 6 条 guide 条目（文件 / 文件变动 / 任务管理 / 侧边对话 / 终端 / 浏览器），**因此在默认组合下，插件与内置类型的说明都不会出现**，六条仍是「图标 + 标题」。
+
+说明只在读者于插件设置页关掉足够多的 tab 类型、把 guide 压到 ≤ 4 条时才出现（逐类型开关；关掉 `editor` 会同时移除接管出去的「文件」行）。这是上游行为而非插件缺陷：插件恢复字段是为了让「关到 ≤ 4 条」的读者拿到真实说明，而不是为了在默认组合里显示什么。指南 §0 与 §4.1 都写明了这条规则，消费插件不应把关键信息只放在 `description` 里。
+
+## 改动清单（子系统级）
+
+| 子系统 | 文件 | 变更 |
+|---|---|---|
+| 基线 | `package.json` | 版本 → `0.19.0`（无后缀）；dsh-* peer 全部 `^0.1.5-rc.1`；devDeps 同步钉 `0.1.5-rc.1`；`dsh-client-locale` 跟随基线到 `0.1.5-rc.1`（该包已回到与 DSH 同 tuple 发版，§3-9 的落后例外保持消除） |
+| 基线 | `pnpm-lock.yaml` | 锁文件对齐 rc.1 |
+| 基线 | `dsh.plugin.json` | `version` → `0.19.0`；`engines.dsh` → `>=0.1.5-rc.1` |
+| 基线 | `.github/workflows/ci.yml` | mount lane 钉 `@deepseek-ai/dsh@0.1.5-rc.1`（rc.1 在 npm 上同时是 `latest` 与 `next`） |
+| 基线 | `package.json` | 上一版提升的第三方 devDependencies（anser / shiki / `@shikijs/langs` / `mdast-util-*` / `micromark-*` / katex）保留不回退——`ui-primitives@0.1.5-rc.1` 仍无 `dependencies` |
+| Tab 契约 | `src/client/service.ts` | `TabDescriptor` 恢复可选 `description`；`SIDEBAR_SERVICE_VERSION` 跟随插件版本（`0.19.0`） |
+| Tab 契约 | `src/client/builtins/tabs.tsx` | 六个内置类型（editor / git / subagent / sidechat / terminal / browser）重新声明 `description` |
+| Tab 契约 | `src/client/native/index.ts` | guide 条目在 descriptor 声明了说明时带上 `description`；未声明就不发该字段（不补通用句） |
+| 词典 | `src/client/locales.ts` + 19 份 `locales-*.ts` | 恢复 6 个 `guideDesc*` 词条（zh / en / ja 与其余第三方语言） |
+| 测试 | `tests/builtins.spec.ts` | 指南断言从「仅 `title`」改回「`title` + `description`」 |
+| 测试 | `tests/native-surface.spec.ts` | 断言 guide 条目携带 `description`；`editor` 类型仍不单独占行、接管行承载其图标与说明 |
+| 文档 | `docs/external-plugin-guide.md` | 顶部基线行（v0.19.0 / DSH 0.1.5-rc.1+ / 两个钉版旧版本）、§0 「新建标签页列表」行、§4.1 恢复 `description` 字段与 ≤4 规则 |
+| 文档 | `docs/plans/2026-09-09-dsh-0.1.5-alpha.2-adaptation.md` | 加一行前向链接（该版删掉的 `description` 在 rc.1 回归） |
+| 文档 | `docs/plans/2026-09-10-dsh-0.1.5-rc.1-adaptation.md` | 本计划 |
+| 文档 | `AGENTS.md` | §2 CI 基线戳、§3 标题与基线 prose、§3 第 9/10 条（devDeps 不回退 / `description` 回归） |
+| 文档 | `README.md` / `README_EN.md` | 顶部与安装节的「支持的 DSH 版本」徽章、安装节正式版说明、新增 `### v0.19.0` 更新段落 |
+
+## 验证
+
+- **本工作流（文档）未执行任何门禁或真机验证**，只做了与工作树现状的交叉核对：`package.json` 为 `0.19.0`（dsh-* peer 与 devDep 均 `0.1.5-rc.1`）、`dsh.plugin.json` 的 `engines.dsh` 为 `>=0.1.5-rc.1`、`.github/workflows/ci.yml` 钉 `@deepseek-ai/dsh@0.1.5-rc.1`、`SIDEBAR_SERVICE_VERSION` 为 `0.19.0`、`src/client/builtins/tabs.tsx` 六个类型与 `src/client/native/index.ts` 的 guide 条目（含 `files` 接管行）重新带上 `description`、`src/client/locales*.ts` 恢复 6 个 `guideDesc*` 键。
+- 仓库**没有守护指南文档章节的测试**——`tests/builtins.spec.ts` / `tests/native-surface.spec.ts` 守护的是 guide 行的形态，不是文档文本，因此文档改动没有对应的测试命令可跑。
+- **待补（由主代理在实施完成后回填，本文件不预填未经执行的结论）**：门禁数字（`pnpm typecheck` / `pnpm lint` / `pnpm vitest run --exclude '**/*.e2e.ts'` / `pnpm peers check`）、`scripts/e2e-mount.sh` 真机挂载车道的通过数，以及本地 3080 实例（DSH 0.1.5-rc.1 + 插件 0.19.0）上的实测结果——默认组合下 6 条 guide 行仍是「图标 + 标题」、关掉 tab 类型至 ≤ 4 条后说明出现、以及 `pageerror` / 控制台状况。
+
+### 回填（主代理实测）
+
+- **门禁**：`pnpm typecheck` / `pnpm lint` / `pnpm check:consumer-types` 全绿；`pnpm vitest run --exclude '**/*.e2e.ts'` = **124 files / 1296 passed / 9 skipped**；`pnpm peers check` = No peer dependency issues found（rc.1 未新增失配的传递 peer，因此没有再提升任何 devDep）。
+- **挂载冒烟**（`DSH_CMD` 指向 npm 安装的 0.1.5-rc.1，`scripts/e2e-mount.sh`）：**7 passed**，含 tab 体填充断言与新增的 ≤4 条描述断言。
+- **≤4 断言的真实形态**：默认 6 条下永远拿不到说明文本，所以该用例先用插件自己的 `settings.get` / `settings.update` 把启用集合压到 3 个类型（files / sidechat / browser），断言 `files` 胶囊文本含英文说明片段 `workspace tree`，并断言被禁用的三个条目离开 guide。
+  - **踩坑（已修）**：恢复设置时最初只把原始 `tabsEnabled`（scratch profile 里是 `{}`）原样发回——而该路由的 patch 是**逐键合并**，空对象清不掉刚写下的三个 `false`，于是同车道的 `perf.e2e.ts` 扫 guide 时找不到 `git` 条目而失败。改为对本次动过的每个键显式恢复（原值缺省即 `true`）后全绿；这条经验对任何"临时改设置再恢复"的 e2e 都适用。
+- **真机 3080**（DSH 0.1.5-rc.1 + 插件 0.19.0）：guide 六行胶囊均为「图标 + 标题」、**无说明**（6 > 4，符合上游规则）；胶囊高度 56px（上游把 `min-height` 从 alpha.2 的 48px 调到 56px）；文件树点击 `AGENTS.md` → tab 标题 `AGENTS.md` + CodeMirror 挂载；sidechat 宿主盒 962px == `.paneBody` 962px（fillGap 0），composer 底边距 8px；底部工作台与 `[data-dsh-center-col]` 左右边完全重合（gap 0）；`pageerror` 0；控制台仅第三方 `dsh-tauri-worktree` 的 `/api/dsh-worktree/attach` 500（alpha.2 期同样存在，与本次无关）。rc.1 真机的 `[data-slot]` 清单与 alpha.2 完全一致（`main` / `main.conversation` / `rightbar` / `rightbar.session`），印证"全局面板模型未变"。
+
+## 不做
+
+- 不为 ≤4 渲染规则裁剪内置 tab 类型、调整条目数或改写图标。
+- 不恢复 `nativeGuideDesc` 通用兜底句。
+- 不接入 alpha.2 的全局面板（`main` 槽 / `sidebar.panellist` / `ctx.layout` / `usePanelInfo` / 根级 `rightbar`）——沿用上一版结论，rc.1 上这些面同样只是兼容保留。
+- 不回退提升进 devDependencies 的第三方包。
+- 不改 DSH 源码（仓库硬约束 §1）。
+
+## 落地
+
+- [#613](https://github.com/omdsh-dev/DSH-better-sidebar/pull/613) 合入 `main`（merge commit `754974a`）；main 的 `package.json` 为 `0.19.0`、`engines.dsh` 为 `>=0.1.5-rc.1`。PR 的 `ci` / `ci-windows` / `plugin-mount` 三个 check 全绿。
+- 发布 [v0.19.0](https://github.com/omdsh-dev/DSH-better-sidebar/releases/tag/v0.19.0)：`release.yml` 通过全门禁后经 npm Trusted Publishing 发布到 **`latest`**（带 provenance）；实测 dist-tags：`latest = 0.19.0`、`alpha = 0.19.0-alpha.1`（不变）、`beta` 不变。
+- 产物核对：`lib/index.js` 与本地已验证构建**逐字节一致**，且与 `v0.19.0-alpha.1` 的同名文件同哈希（宿主侧代码在这两版之间确实没动）；`lib/client.js` 仅差已知的打包非确定性；发布包的 client bundle 内含恢复后的说明文案。
+- **npm 传播延迟仍是 ~4–5 分钟**：06:49:10 工作流报 `Published package dsh-better-sidebar@0.19.0`，06:53:53 dist-tags 才可见 `latest = 0.19.0`（版本元数据与 tarball 依次到达，期间 `npm view` / tarball 会 404）。这不是发布失败，别重发。

docs/plans/2026-09-10-dsh-0.1.5-rc.2-adaptation.md

@@ -0,0 +1,104 @@
+# DSH 0.1.5-rc.2 适配（v0.19.1 基线）+ CI 三类失败修复
+
+日期：2026-09-10（复核 2026-09-11）　分支：`feat/dsh-0.1.5-rc.2`
+
+## 背景
+
+DSH `dsh-v0.1.5-rc.1..dsh-v0.1.5-rc.2`（上游 4 个 commit / 300 个变更文件，npm 发布 2026-09-10T14:57Z，dist-tag **`next`**；`latest` 仍是 rc.1）是 0.1.5 线的第二个候选版。本计划记录该 delta、插件对它的结论（**无需任何运行时/类型层适配**，只推进钉版），以及同一时间窗内 `ci-windows` / `plugin-mount` 两个车道真实存在的三类 CI 失败与修法。上一版（rc.1）记录见 [2026-09-10-dsh-0.1.5-rc.1-adaptation.md](./2026-09-10-dsh-0.1.5-rc.1-adaptation.md)；仓库级适配要点同步到 [AGENTS.md](../../AGENTS.md) §2/§3。
+
+## 上游 delta（rc.1 → rc.2，影响本插件的部分：无）
+
+300 个文件里绝大多数是各包 `package.json` 的 `version` 单行改动（`1+1-`）。逐文件过完后的真实代码改动只有四处：
+
+| # | 上游变更 | 文件 | 对插件的影响 |
+|---|---|---|---|
+| 1 | 消息反馈改为对称提交（弹窗、动作按钮、控制器、槽位、i18n） | `packages/client/ui-message-feedback/src/client/*` | 无——插件不注册反馈槽、不读该控制器 |
+| 2 | 产物卡片内边距与呈现微调 | `packages/client/ui-deliverables/src/client/*`、`ui-chat/src/client/chat/TurnTailNodeView.module.css` | 无——插件不消费这两个包的组件，也不做会话尾迹布局 |
+| 3 | `CodeFileIcon` 的 477 行内联 SVG 拆进新增的 `code-file-icon-artwork.ts`（另有 `.manifest.json` 记录设计导出摘要） | `packages/client/ui-primitives/src/CodeFileIcon.tsx` | 无——`CodeFileIcon` 的导出面与 props 未变，且插件**本来就不用它**（插件文件树用 `IconCodeOutline16`；`#611` 的文件图标主题还在 PR #594，未进 main） |
+| 4 | 其余全部为版本号 | 各 `package.json` | 无 |
+
+**明确未变（不必再核）**：
+
+- `packages/api/*`（session-controller / workspace-controller / gateway / remotes）、`packages/host/*`、`packages/session/*`、`packages/agent/*`——**零**变更；除 `packages/feedback/message-feedback/src/types.ts`（1 行）外**零**类型文件变更。
+- 斜杠 RPC 方言、一次性 token 鉴权、会话事件模型、`sidebarRight` / `sidebarRightTabs` 承载面、`SidebarRightGuideEntry.description` 的 ≤4 渲染规则：全部沿用 rc.1 结论。
+- `@deepseek-ai/dsh-client-ui-primitives` 仍不声明 `dependencies`（bundle 仍裸 import `anser` / `shiki` / `@shikijs/langs/*` / `mdast-util-*` / `micromark-*` / `katex`）——提升进 devDependencies 的那组包继续不得回退。
+
+## 决策
+
+- **peer 下限保持 `^0.1.5-rc.1` 不动**：rc.2 无契约变化，`^0.1.5-rc.1` 天然容纳它，rc.1 用户无需升级即可用新版插件。因此本版是**纯 patch 的 0.19.1**，只推进 devDependency 钉版、CI 挂载钉版与 `SIDEBAR_SERVICE_VERSION`。
+- **`engines.dsh` 保持 `>=0.1.5-rc.1`**：与 peer 下限同源（同一个支持范围，两处不能分叉）。
+- **CI 挂载车道钉 rc.2**：真机证据要落在最新版上；`latest` 仍是 rc.1 只是上游的发布节奏，与本插件支持范围无关。
+- **不为此版写运行时兼容层**：上游 delta 里没有本插件触达的面，写兼容层就是无据的复杂度。
+
+## CI 三类失败（2026-09-09/10 窗口，60 次已完成 run 的取证）
+
+窗口内 `ci-windows|Test` 失败 8 次、`plugin-mount|Install dsh CLI (pinned)` 失败 4 次。逐条读日志后归为三类，其中两类是**真实缺陷**、一类是**运维噪音**：
+
+### A. Windows 真实超时（6/8 次 `ci-windows` 失败，主因）
+
+- 证据：run `34494370187`、`34490215638`、`34459499945`（**3 次 attempt 全红**）、`34372999975`、`34322271074`、`34319666611` 均为 `Error: Test timed out in 5000ms`，位置 `tests/agent-pty.spec.ts:71:3` / `:106:3`；`tests/install-powershell.spec.ts:105:41` 的 `powershell.exe` 单测自身耗时 **12151ms** 后才超时。
+- 根因：`vitest.config.ts` 没有任何 `testTimeout` 配置（默认 5000ms），而这些 spec 每个用例都要真起一个 `PowerShell + ConPTY` 对；`tests/agent-pty.spec.ts` 的 `waitForTranscript` 默认预算**也**是 5000ms——内层轮询吃掉整个对外预算，结构上必然超时。
+- 修法：**全局** `testTimeout: 15_000`（`vitest.config.ts`）+ 两个最重的 describe 显式 `{ timeout: 30_000 }`（vitest 4 的 describe 级选项，已实测生效）+ `waitForTranscript` 默认预算降到 15s。**为什么是全局而不是逐文件**：本 PR 第一次跑真实 Windows 时，同一个 5000ms 默认又在**第三个文件**上翻车——`tests/git.spec.ts:85`「caps status entries at the truncation limit」耗时 **9607ms**（构造病态 untracked 集合 + 真实 git 调用）。三个不同文件、同一个根因，逐文件加超时是打地鼠；15s 是默认值的 3 倍、也是 Windows 上实测最大单测耗时的 ~1.5 倍，而 pty / powershell 两类最重的用例各有自己的 30s 预算。
+
+### B. Windows worker 静默死亡（2 次，非确定性）
+
+- 证据：run `34500290681`(295615abb)、`34448911025`(bbf953b8a) 报 `[vitest-pool]: Worker forks emitted error / Caused by: Error: Worker exited unexpectedly`（`Errors 1 error`），同一份日志里 `0 FAIL`、125 个文件全过；后者静默吞掉一个文件的 10 条结果。同一 commit `8ae527170` 的另一次 run 里 `ci-windows` 是**绿的** → 该步骤可证伪地非确定。
+- 归因（**推断，非确证**）：真起进程的 spec 有 5 个（`agent-pty` / `pty-deps` / `pty-helpers` / `install-powershell` / `smoke`），node-pty 的 ConPTY 辅助进程与冷启 `powershell.exe` 都绑定控制台，在默认**无界 fork 池**下并行抢占；本地 macOS 无法复现该模式，因此不做无证据的猜测性改动（不加 `retry`，不改默认 pool）。
+- 修法（两次迭代，第一次被真实结果证否）：先上 `test:windows`（`vitest run --maxWorkers=2`）——**真实 Windows 上仍复现**（run `34574847774`：126/127 文件全过、`0 FAIL`、`Unhandled Error: Worker exited unexpectedly`，丢结果的那个 worker 正是跑 `tests/native-surface.spec.ts` 的）。该次日志里 `native-surface.spec.ts` **零结果**，与历史两次崩溃同形（`34500290681` 125/126、`34448911025` 123/124——都是「N-1 个文件有结果 + teardown 期 worker 静默退出」）。
+- 迭代后的修法：`--maxWorkers=1`（整个套件跑在一个 fork 里，**零 worker 回收**）。理由：跨 4 次崩溃的一致形态是「worker 回收/退出竞态」，而不是某个测试失败；单 worker 从根上取消这个竞态，代价只是墙钟时间（本地 14s → 41s，Windows 步骤仍在 30 分钟 job 预算内）。**仍不加 retry**：retry 会把真实回归一起吞掉。
+
+### C. `plugin-mount` 的 npm 安装失败（4 次：2× ETARGET + 2× OOM）
+
+- 证据：run `34492160123` / `34491256626` 报 `npm error notarget No matching version found for @deepseek-ai/dsh-tool-bash-persistent@^0.1.5-rc.2` / `@deepseek-ai/dsh-sandbox-windows-acl@^0.1.5-rc.2`；run `34490912649` 先刷 **3062 条 ERESOLVE**、9 分钟后 `FATAL ERROR: Ineffective mark-compacts near heap limit` exit 134。同一机制在 2026-09-09 的 alpha 线也复现过一次（run `34363627184`，1808 条 ERESOLVE → OOM）；同期成功的安装是 `added 521 packages in 19s`、**0 条 ERESOLVE**。
+- 根因：**钉版并没有真的钉住**。`@deepseek-ai/dsh@0.1.5-rc.1` 的传递依赖声明为浮动 `^0.1.5-rc.1`，会被上游**分阶段发布**中的 rc.2 满足（rc.2 的 14:43–14:57 逐个包上线），于是 npm 组出 rc.1/rc.2 混合 peer 图 → 解析器爆炸（OOM），或对尚未发布的兄弟包硬报 ETARGET（两个 ETARGET 分别在该包上线前 5.5 分钟与 25 秒）。
+- 修法（`.github/workflows/ci.yml`）：钉一个**已完整发布**的 rc.2（修 ETARGET），并加 `NODE_OPTIONS=--max-old-space-size=4096`（修 OOM）。
+- **一次被真实结果否掉的中间方案（值得记）**：第一版修复还加了 `--legacy-peer-deps`（想法是「跳过 peer 协商即与发布窗口解耦」）。真实 Windows 结果表明它只是把安装**弄坏**而不是弄稳：它跳过的正是全局安装必须提供的 peer，而 `@deepseek-ai/dsh-app-boot` 在 boot 时 require 的 `@deepseek-ai/cordis-plugin-group` **是 peer 而不是 dependency**，于是 CLI 在冒烟开始前就以 `ERR_MODULE_NOT_FOUND` 死掉（run 34560785101 的 `plugin-mount`）。本地复现并验证：同一命令去掉该 flag 后安装树完整（`dsh/node_modules/@deepseek-ai/cordis-plugin-group` 存在），且 `DSH_CMD` 指向这个 classic 安装的 `test:mount` **7 passed**——宿主自带依赖，插件侧看不到差别。
+- 顺带修掉一处过时注释（原文断言「rc.1 同时是 `latest` 与 `next`」——现在 `latest=rc.1`、`next=rc.2`）；这条注释正是浮动范围隐患长期不可见的来源。
+
+## 改动清单（子系统级）
+
+| 子系统 | 文件 | 变更 |
+|---|---|---|
+| 基线 | `package.json` | `version` → `0.19.1`；dsh-* **devDependencies** 全部钉 `0.1.5-rc.2`（含 `dsh-client-locale`，上游仍与 DSH 同 tuple 发版）；**peerDependencies 一律保持 `^0.1.5-rc.1`** |
+| 基线 | `pnpm-lock.yaml` | 锁文件对齐 rc.2 |
+| 基线 | `dsh.plugin.json` | `version` → `0.19.1`；`engines.dsh` 保持 `>=0.1.5-rc.1`（与 peer 下限同源） |
+| 基线 | `src/client/service.ts` | `SIDEBAR_SERVICE_VERSION` → `0.19.1`（`tests/service.spec.ts` 断言它 === `package.json` 的 version） |
+| CI | `.github/workflows/ci.yml` | mount 车道钉 `@deepseek-ai/dsh@0.1.5-rc.2` + `NODE_OPTIONS=--max-old-space-size=4096`（C 类；**不用** `--legacy-peer-deps`，理由见 C 节）；`ci-windows` 的 `Test` 改跑 `pnpm test:windows`（B 类）；注释同步事实 |
+| CI | `package.json` | 新增 `scripts.test:windows`（`vitest run --maxWorkers=2`） |
+| CI | `vitest.config.ts` | 全局 `testTimeout: 15_000`（A 类；覆盖 git / powershell / pty 三类真起进程的 spec，逐文件打地鼠的做法在真实 Windows 上被证否） |
+| CI | `tests/agent-pty.spec.ts` | `AgentPtyRegistry` describe 显式 `{ timeout: 30_000 }`；`waitForTranscript` 默认预算 5000 → 15_000（A 类） |
+| CI | `tests/install-powershell.spec.ts` | `PowerShell installer entry points` describe 显式 `{ timeout: 30_000 }`（A 类） |
+| 文档 | `docs/plans/2026-09-10-dsh-0.1.5-rc.2-adaptation.md` | 本计划 |
+| 图标 | `src/client/file-icons.tsx` / `src/client/builtins/tab-icons.*` / `src/client/native/tab-adapter.tsx` | 文件图标改用宿主官方 `FileTypeIcon`；内置 tab 与原生芯片图标彩色——独立记录见 [2026-09-11-file-icons-and-tab-glyphs.md](./2026-09-11-file-icons-and-tab-glyphs.md) |
+| 文档 | `AGENTS.md` | §2 CI 基线戳与 mount 车道说明、§3 标题/基线段（rc.2 仍无契约变化，只推进钉版） |
+| 文档 | `README.md` / `README_EN.md` | 支持版本徽章与说明、新增 `### v0.19.1` 段 |
+| 文档 | `docs/external-plugin-guide.md` | 顶部基线行 → v0.19.1 / DSH 0.1.5-rc.1+（已在 rc.2 上验证） |
+| 文档 | `tests/native-surface.spec.ts`、`tests/builtins.spec.ts`、`tests/e2e/mount.e2e.ts`、`src/client/service.ts`、`src/client/native/index.ts` | 注释里的 `DSH 0.1.5-rc.1` → `0.1.5-rc.1+`（同一行为在 rc.2 未变） |
+
+## 验证
+
+- **未执行**的门禁与真机步骤都留空，由主代理实施后回填（本文件不预填未经执行的结论）。
+
+### 回填（主代理实测）
+
+- **门禁（rc.2 钉版，macOS arm64）**：`pnpm install` 成功且锁文件对齐 rc.2；`pnpm peers check` = `No peer dependency issues found`；`pnpm typecheck` / `pnpm lint` / `pnpm check:consumer-types` 全绿；`pnpm test` = **126 files / 1312 passed / 9 skipped**（与 rc.1 基线同数，无新增 skip）。
+- **真机挂载冒烟（rc.2）**：`DSH_CMD` 指向 `npx -y --package @deepseek-ai/dsh@0.1.5-rc.2 dsh`；见"落地"节的实测计数。
+- **真实 Windows 收敛**：`ci-windows` **连续两次全绿**（同一 commit `5451f5c`）——`pull_request` 自动触发的 run [34561189320](https://github.com/omdsh-dev/DSH-better-sidebar/actions/runs/34561189320) 与随后 `workflow_dispatch` 的 run [34561457067](https://github.com/omdsh-dev/DSH-better-sidebar/actions/runs/34561457067)，两次都是 **126 files / 1318 passed / 3 skipped / 0 errors**（`Unhandled Errors` 与 `Worker exited unexpectedly` 出现次数均为 **0**；同环境的 2026-09-09/10 窗口里这两行出现过 2 次）。同一分支的 `plugin-mount` 两次都绿：`added 521 packages in 24s`（**0 条 ERESOLVE**，与历史 OOM run 的 3062 条对比）、`test:mount` **7 passed**、聚合双挂载通过。
+- **首次真实结果的证伪（已修正）**：本 PR 的第一版修复在同一 commit 上仍红两处，`.github/workflows/ci.yml` 的改动因此被真实证据改过一轮——见 C 节的「一次被真实结果否掉的中间方案」与 A 节第三个文件（`tests/git.spec.ts:85`，9607ms）。
+- **B 类的实测结论（已按"升级而非掩盖"走完两轮）**：`--maxWorkers=2` 下仍崩溃（run `34574847774`），故升级为 `--maxWorkers=1`（单 fork、零回收）。这**不等于证明了根因**（4 次崩溃的一致形态是「N-1 文件有结果 + teardown 期静默退出」，只能说明是 worker 回收竞态而非测试失败）；收敛判据是单 worker 下连续两次 `ci-windows` 全绿——**已达成**：run [34575721734](https://github.com/omdsh-dev/DSH-better-sidebar/actions/runs/34575721734)（PR 触发）与 run [34576146970](https://github.com/omdsh-dev/DSH-better-sidebar/actions/runs/34576146970)（同 commit `4fe67e3` 的 `workflow_dispatch`）都是 **127 files / 0 errors**，`Unhandled Errors` 与 `Worker exited unexpectedly` 出现 0 次。
+- **本地 3080 真机**（DSH 0.1.5-rc.2 + 插件 0.19.1）：部署与路由探针已完成（见"落地"节），GUI 人工验证由用户执行。
+
+## 不做
+
+- 不为 rc.2 写任何运行时/类型层兼容层（上游 delta 未触及本插件的面）。
+- 不把 peer 下限抬到 `^0.1.5-rc.2`（会无谓地把 rc.1 用户挡在上一版）。
+- 不为 B 类做无证据的猜测性改动：不加 vitest `retry`、不改默认 pool、不关掉真实 pty 测试。
+- 不改 DSH 源码（仓库硬约束 §1）；不改 `release.yml`（0.19.1 无 prerelease 后缀 → 自动发 `latest`，符合 patch 语义）。
+
+## 落地
+
+- PR：[#626](https://github.com/omdsh-dev/DSH-better-sidebar/pull/626)（`feat/dsh-0.1.5-rc.2`）。
+- 本地真机挂载冒烟（rc.2，macOS arm64）：`pnpm test:mount` **7 passed**（含 tab 体填充断言、指南 ≤4 条说明渲染断言、mermaid / README 预览与 sidechat 路由烟测）；`pnpm test:mount:aggregate` 通过（聚合双挂载下插件自动退让，`/sidebar/api` 未知方法 404 与 `terminal.deps` 契约均符合）。
+- 本地 3080 实例部署（`~/.dsh/profiles/web` + `~/.dsh/dsh-web.sh`）：profile 依赖从 `dsh-better-sidebar-0.19.0.tgz` 改指 0.19.1 tarball 并 `pnpm install`（`node_modules/dsh-better-sidebar/package.json` = **0.19.1**）；`dsh-web.sh` 的 npx 钉版改 `@deepseek-ai/dsh@0.1.5-rc.2`，旧进程（PID 99521/99509/99507）定向 kill 后由 LaunchAgent `com.pm2.dshweb.resurrect` 自动拉起（新 PID 36025，npx 缓存 hash 因版本变更从 `1da1392061ab1944` 变为 `c40503fdf38a82ea`）。**已核**：新缓存里的 `@deepseek-ai/dsh` = **0.1.5-rc.2**，`/sidebar/api/shell.get` → `{"ok":true,"value":{"shell":"zsh","name":"zsh"}}`、`settings.get` 回默认设置、`terminal.deps` → `{"ok":true}`（三条插件路由在生产实例上工作）；GUI 人工验证由用户执行，结论回填到本节的下一步。
+- PR：[#626](https://github.com/omdsh-dev/DSH-better-sidebar/pull/626)（`feat/dsh-0.1.5-rc.2`）。PR 三个 check（`ci` / `ci-windows` / `plugin-mount`）在 run 34561189320 与 run 34561457067 上均绿。
+- 待回填：3080 人工验证结果（用户执行）、发版情况（v0.19.1 的 tag / npm 发布由用户决定）。

docs/plans/2026-09-11-file-icons-and-tab-glyphs.md

@@ -0,0 +1,92 @@
+# 文件图标与彩色 Tab 图标（v0.19.1，#531 + #594 合并后的重做）
+
+日期：2026-09-11　分支：`feat/dsh-0.1.5-rc.2`（并入 PR [#626](https://github.com/omdsh-dev/DSH-better-sidebar/pull/626)）
+
+## 背景与决策
+
+[#611](https://github.com/omdsh-dev/DSH-better-sidebar/issues/611) 希望文件树按类型显示图标（「仿照官方做法」），[#429](https://github.com/omdsh-dev/DSH-better-sidebar/pull/429)（@fenter）为此做了 563 条彩色图标数据，落成两个叠着的 PR：
+
+- [#531](https://github.com/omdsh-dev/DSH-better-sidebar/pull/531)（`feat/file-icons-api`，base=main）：文件树/文件 tab 按扩展名分图标 + 对外 `registerFileIcon` API；
+- [#594](https://github.com/omdsh-dev/DSH-better-sidebar/pull/594)（`feat/file-icon-theme`，base=#531 分支）：在其上叠「内置单色 / 彩色品牌图标」可选主题，彩色数据做成懒加载 chunk（255 kB）+ 设置页开关。
+
+两者在 2026-09-08 都绿，但都基于 v0.18.1、落后 main 55 个 commit，且与 DSH 0.1.5-rc.2 的一个新事实冲突：**rc.2 的 `ui-primitives` 已经导出官方文件类型图形** `FileTypeIcon` / `CodeFileIcon`（48 类全彩代码/配置图形 + 12 类类目色板图形 + `classifyFileType` 分类器）。也就是 #611 想要的东西上游自己做了。
+
+用户决策（2026-09-11）：**两个 PR 都合、并进 v0.19.1 一个 PR；文件图标改用宿主官方 `FileTypeIcon`；内置 tab 图标彩色 + 原生右侧栏芯片也加图标；删掉主题开关，彩色即唯一行为。**
+
+## 上游事实（实测，非推断）
+
+| 事实 | 证据 |
+|---|---|
+| 宿主导出官方图形 | `@deepseek-ai/dsh-client-ui-primitives@0.1.5-rc.2` 的 `lib/types/index.d.ts` 导出 `FileTypeIcon`、`classifyFileType`、`fileExtension`、`CodeFileIcon`、`isCodeFileType` 与 `CodeFileType` 类型；`FileTypeIcon` 声明 `size` 默认 28 并透传给内部 `FileGlyph`/`CodeFileIcon`（14px 树行可用） |
+| 全彩图形保留自己的调色板 | `CodeFileIcon.d.ts` 的文档原话「its identifying palette intact」；`kind:'folder'` 落宿主的 `IconFolderClose16`（单色，随 `currentColor`） |
+| 分类器不返回文件夹 | `classifyFileType` 只走 `classifyCodeFileType ?? NAME_TYPES ?? EXTENSION_TYPES ?? 'other'`，`'folder'` 只能由调用方以 `kind` 显式指定 |
+| 官方图形在 rc.1 就有 | `npm pack @deepseek-ai/dsh-client-ui-primitives@0.1.5-rc.1` 的 tarball 内含 `lib/FileTypeIcon.module.css` 与 `lib/types/{FileTypeIcon,CodeFileIcon,code-file-types}.d.ts`（rc.2 只是把 SVG 数据拆进 `code-file-icon-artwork.ts`） |
+| 原生 tab 定义没有 icon 字段 | `dsh-client-ui-sidebar-right` 的 `SidebarRightTabDefinition` 只有 `id/kind/patterns/priority/canOpen/title/guide`；`icon` 只在 `SidebarRightGuideEntry` 上 |
+| 但 title 槽就是芯片内容 | 宿主 `contract/slots.d.ts`：`'sidebar.right.pane.tab.title'` —— 「A tab's title as its chip (and a floating panel's header) shows it」 |
+
+## 合并（3 处冲突，均为注释/列表并集）
+
+| 文件 | 冲突 | 解法 |
+|---|---|---|
+| `src/client/service.ts` | ① import 区（main 保留 `extOf`，PR 侧已改成 `baseName, extOf` + 自己的 `isNarrowWidth`）② `SIDEBAR_FEATURES` 注释与列表（main 写「v0.19.0 删除了 floatWindows」，PR 侧在旧清单上加 `'fileIcons'`） | ① 取 `baseName, extOf`：`isNarrowWidth` 属于 PR 自己的「新建会话按视口折叠」逻辑，main 已把那套 seeding 重写掉，合并后该 import 是死代码（实测 grep 确认后删除）。② 并集：保留「已移除 floatWindows」措辞 + 追加 `'fileIcons'` |
+| `src/client/Sidebar.tsx` | `tabIconOf` 上方注释（两侧各改一句） | 并集：保留 main 的「The tab icon from the tab-type registry.」并补 PR 侧「带 path 的编辑器 tab 显示文件图标」的说明 |
+| `docs/external-plugin-guide.md` | `features` 清单注释 | 并集：main 的新措辞（只增不删，唯一例外 v0.19.0 删除 floatWindows）+ `'fileIcons'` |
+
+#594 的其余冲突（`tests/plugin-shape.spec.ts`、`tests/prefs.spec.ts`）**取本线一侧**：main 已删除这两个文件里的 store-seeding 用例并重写了 schema 断言（`SIDEBAR_PREFS_DEFAULTS` 解构），PR 侧重新加回的块描述的是 main 不再存在的行为——把旧块带回来只会测到死代码。
+
+## 重做（把 #594 的彩色实现换成宿主官方图形）
+
+### 删除
+
+- `src/client/chunks/file-icons.tsx`（563 条数据）、`src/client/file-icon-theme.ts`（chunk loader）、`tests/file-icon-theme.spec.tsx`；
+- `fileIconTheme` pref 三处（`prefs-shared.ts` / `src/config.ts` / `src/client/prefs.ts`）、设置页「文件图标」select 行、20 份词典里的 6 个 `settingsFileIconTheme*` key（共 126 行）；
+- chunk 注册三处（`src/bundle-route.ts` 的 `CHUNK_NAMES`、`src/client/chunk-loader.ts` 的 `ChunkName`、`tsdown.config.ts` 的 `CHUNKS` 与 react-icons alias）与对应测试期望（`bundle-route.spec.ts` / `manifest-consistency.spec.ts`）；
+- `src/client/index.tsx` 里驱动主题 loader 的 effect。
+
+### 新增/改写
+
+| 位置 | 内容 |
+|---|---|
+| `src/client/file-icons.tsx` | `builtinFileIcon(path, size)` → `<FileTypeIcon path size />`；`builtinFolderIcon` → `<FileTypeIcon kind="folder" size />`（宿主只有一个文件夹图形，开/合两态不另画）；`fallbackFileIcon(size)` → `<FileTypeIcon kind="other" size />` |
+| `src/client/service.ts` 的 `fileIcon` 链 | 具体注册 → **catch-all 全局默认 → 宿主图形**（原先 built-in map 排在 catch-all 之前） |
+| `src/client/builtins/tab-icons.tsx` + `.module.css` | 六个内置类型 + diff 视图的彩色 glyph；颜色全部 `var(--dsw-alias-*)`（files=brand、changes=success、tasks=warn、sidechat/browser=business、terminal=label-primary，各带 fallback 链） |
+| `src/client/native/tab-adapter.tsx` 的 `NativeTabTitle` | 渲染 `[glyph][title]`：编辑器 tab 带 path 时用 `service.fileIcon(path, 14)`，其余用 `descriptor.icon(14)`；glyph `aria-hidden`；`NativeTitleInjected` 增加 `service` 与 `descriptorId`，`registerSlots` 的 title 注入同步 |
+| `src/client/sidebar.module.css` | 新增 `.chipIcon`（芯片 glyph 的排版，颜色继承） |
+| `tests/theme.spec.ts` | 豁免段整体删除，改为三条守护：图标模块零颜色字面量、`tab-icons.module.css` 里每条 `color` 都解析到 `var(--dsw-`、`src/client/chunks/*` 不含 6 位颜色字面量（图标数据不得再做回 chunk） |
+| `tests/file-icons.spec.tsx` | 内置断言从 codicon 身份改为宿主 `FileTypeIcon`；新增「path/size 透传」「文件夹用 `kind:'folder'`」；catch-all 用例改写为「注册了 catch-all 就接管全部未具体命中的行」 |
+| `tests/native-surface.spec.ts` | 新增 3 例芯片 glyph：descriptor glyph 在标题前、编辑器 tab 用文件图标而非类型图标、类型注销后只剩标题 |
+
+## 语义后果（必须写进文档）
+
+**宿主分类器覆盖任意路径**，因此「插件自己已经能画这个扩展名」不再是拦住 catch-all 的理由：注册 `exts: []` 的插件现在会接管所有未具体命中的文件行（原先会被内置 map 拦下）。旧版彩色主题那种「整表注册、靠内置 map 兜底」的形态不再成立——只想补几个类型的插件用 `exts`/`names`。已写进 [指南 §7](../external-plugin-guide.md) 与 [AGENTS.md](../../AGENTS.md) §5。
+
+## 验证
+
+**已执行（macOS arm64，DSH 0.1.5-rc.2 钉版）**
+
+- `pnpm typecheck` / `pnpm lint` / `pnpm check:consumer-types` 全绿；
+- `pnpm test` = **127 files / 1343 passed / 9 skipped**（v0.19.1 基线 126/1312 + 合并与新增的 31 例，失败数 0；返工后 +1 例 glyph 身份断言）；
+- `pnpm build`：`lib/client.js` **0.85 → 0.86 MB**（+10 kB），**没有** `lib/client-file-icons.js`；核心 bundle 内不含图标数据（只有 6 个被引用的 glyph 组件）；
+- 真机挂载冒烟（`DSH_CMD` 指向 `@deepseek-ai/dsh@0.1.5-rc.2`）：`pnpm test:mount` **7 passed**（含 guide 深扫、tab 体填充断言、mermaid/README 预览、sidechat 路由），`pnpm test:mount:aggregate` 通过。
+
+### 真机反馈的两处返工（用户人工验证后）
+
+| 反馈 | 结论与改动 |
+|---|---|
+| 「任务管理」图标不对——该页是 subagent + 后台 jobs，不是 todo | `VscTasklist`（清单）→ **`VscLayers`**（多层堆叠 = 后台在跑的工作）。`tests/builtins.spec.ts` 用 glyph 身份把这条读法钉住 |
+| 终端图标「非常怪」 | 根因是**观感权重**：`VscTerminal` 是整套里最宽的实心矩形，在 14px 下比邻座重。**只缩小一档**（`0.85 × size`，下限 10px）——形状与绘制方式保持图标集原样 |
+| 追加反馈：上一版给全部 tab glyph 加的 `currentColor` 发丝描边（`strokeWidth: 1` + `non-scaling-stroke`）「太粗」 | **整体回退**：不描边，glyph 只用包裹类的令牌着色。“描边”是我对「怪」的过度解读，反馈的本意只是终端尺寸。`tests/builtins.spec.ts` 现在同时钉住「终端尺寸更小」与「glyph 不带 style 覆盖」，防止描边再溜回来 |
+
+### 真实 CI（已收敛）
+
+`ci` / `plugin-mount` 每轮都绿；`ci-windows` 的 worker 回收竞态在 `--maxWorkers=1`（单 fork、零回收）下**连续三次全绿**：run [34575721734](https://github.com/omdsh-dev/DSH-better-sidebar/actions/runs/34575721734)、[34576146970](https://github.com/omdsh-dev/DSH-better-sidebar/actions/runs/34576146970)、[34576493202](https://github.com/omdsh-dev/DSH-better-sidebar/actions/runs/34576493202)，均 **127 files / 0 errors**。两轮迭代（`--maxWorkers=2` 被真实结果证否）的取证见 [rc.2 计划 §B](./2026-09-10-dsh-0.1.5-rc.2-adaptation.md)。
+
+**待验证**
+
+- 3080 人工验证（返工后第二轮）：树行与编辑器 tab 的彩色图标、指南六行彩色、原生右侧栏芯片图标、14px 下官方 48 类图形的可读性、以及这次返工后的任务/终端两个图标（用户此前明确选择用官方图形；若细节折损不可接受，回退方案是「树行用官方图形、编辑器 tab 保留插件 glyph 着色」，改动只在 `file-icons.tsx` 一处）。
+
+## 不做
+
+- 不改 DSH 源码；不把 #429 的 563 条数据搬回仓库（要走按需加载也应按懒加载 chunk 走，而不是常驻数据）；
+- 不为彩色图标新增皮肤契约豁免（插件侧零硬编码颜色）；
+- 不恢复 `floatWindows`；不动已合入的 rc.2 基线结论与 CI 修复。

docs/wiki/01-需求分析.md

@@ -0,0 +1,185 @@
+# 01 · 需求分析：官方原生右列 vs 装了 apes-sidebar
+
+> 本篇只回答一个问题：**一个在 DSH 里干活的人，从"官方原生"换到"装了这个包"，他的需求和处境发生了什么变化？**
+> 对比的两端只有两个：**官方原生的右侧栏**，和**装了 apes-sidebar 之后的右侧栏**（那个包是一个整体，九个 tab 一起算）。
+> 机制与根因只在[附录 A](#附录-a--证据与实现索引)留索引，细节见 [02-系统架构](02-系统架构)、[06-故障排查](06-故障排查)。
+
+## 一、先钉住"谁在用、他在哪儿干活"
+
+在 DSH 里，**右侧栏是使用者一天里盯得最久的一块地方**。它不是"偶尔打开的设置页"，而是"工作台 + 仪表盘"。
+
+一个典型使用者（在 DSH 里做项目的人）：
+
+- 中间是对话主线——他和模型一起干活；
+- 右边是这块地方——看文件、看改动、看子代理、顺手追问、跑命令、看预览；
+- 他往往同时开着好几个会话、好几个项目。
+
+这决定了本页所有需求的共同特征：**这些信息"看一眼就够，但要频繁看"。**
+频繁看的东西必须常驻在视野里——不能要求他"跳出去看一眼，再跳回来"。
+
+## 二、官方原生的右列：一个「只读的文件浏览器 + 预览器」
+
+本机宿主（`dsh@0.1.5-rc.2`）里，官方真正放进右列的东西只有三件：
+
+| 官方包 | 它给用户什么 | 官方原话 |
+| --- | --- | --- |
+| `dsh-client-ui-sidebar-right` | **容器**：每会话一块可停靠面板、两种形态（贴靠 / 全屏）、展开按钮在会话 header 角落、最多左右两格、拖拽与浮窗、tab 菜单、内置撤销历史 | "为每个会话持有一个停靠面……拥有导航控制器（`ctx.sidebarRight`）、tab 类型注册表" |
+| `dsh-client-ui-sidebar-files` | **唯一的页**：「文件」——把会话工作区根目录画成一棵**只读**的树 | "把会话的工作区根目录画成一棵树，逐层经线上列出，并把文件打开到 Sidebar 里" |
+| `dsh-client-ui-sidebar-documentpreview` | **唯一的查看器**（kind = `text`）：预览 Markdown / 代码 / 图片 / PDF / HTML，认不出的扩展名走**纯文本兜底** | "在右侧 Sidebar 预览**可读文件**，无需另开 tab 即可切换已注册的渲染器" |
+
+一个容易被忽略、但对"用户体验"影响很大的细节：
+
+> 引导页（罗盘）**只在注册了两个以上入口时才出现**——官方随包只有一个入口（Files），
+> 所以官方用户的右列**默认直接就是那棵文件树，罗盘从不露面**。
+> （原文："恰好一个入口时直接打开对应页面（随包组合中为 Files）"。）
+
+**一句话概括官方原生的取向：它假设你只是想「看」。**
+它给你树和预览，都是只读的；**它不假设你要在这块地方「干活」**。
+
+于是，官方原生用户在右列里**做不到**这些事（每一条都是他能直接感知的缺失）：
+
+| 他想做的事 | 官方原生右列 | 他只能怎么办 |
+| --- | --- | --- |
+| 改一个文件 | ❌ 只有预览，没有可写的编辑器 | 跳出去，用外部编辑器打开 |
+| 知道刚才改了哪些东西 | ❌ 没有变更清单、没有 diff | 切终端敲 `git status` / `git diff`，或另开 diff 工具 |
+| 看某个子代理干了什么 | ❌ 右列里没有这个入口 | 翻会话树、翻聊天记录去认人 |
+| 追问一句又不想弄脏主线 | ❌ 没有旁路对话 | 硬着头皮在主对话里问，或另开一个窗口 |
+| 跑一条命令 | ❌ 没有终端 | 切到系统终端，还得先 `cd` 到对的目录 |
+| 看页面 / HTML 出来什么样 | ❌ 没有内嵌浏览器 | 切浏览器标签，或手动打开产物文件 |
+| 知道谁在替我干活、跑到哪了 | ❌ 完全没有 | 只能往上翻记录，翻到一半又忘了上下文 |
+| 知道这摊活是在哪儿干的 | ❌ 界面不写 | 靠脑子记，或敲 `pwd` 确认 |
+| 知道这个会话现在什么状态 | ❌ 界面不写 | 靠界面上的小细节猜 |
+
+## 三、装了 apes-sidebar 之后：同一块地方，从「看」变成「干 + 心里有数」
+
+apes-sidebar 把这九件事一次性放进右列。它们**是一个整体需求**：把右列从"文件浏览器"变成"工作台 + 仪表盘"。
+
+| tab | 他真正想要的是什么 | 官方原生时他被迫怎么做 | 装了之后 | 需求被改变成 |
+| --- | --- | --- | --- | --- |
+| 文件（编辑器） | 看**和改**代码，而不丢掉当前上下文 | ⌘Tab 跳到外部编辑器；回来要重新找位置 | 右列里直接看、直接改 | 「看文件不该让我离开现场」 |
+| 文件变动（git） | 刚才到底改了哪些东西 | 切终端敲命令，或另开 diff 工具 | 变更清单 + 单文件 diff，就在旁边 | 「改了什么必须当场看得见」——**这是信任的前提** |
+| 子代理 | 进某个子代理，看它到底干了什么 | 翻会话树、翻记录去认人 | 右列里直接进入该子代理 | 「子代理是可进入的，不是只能干等的」 |
+| 侧边对话 | 追问一句，但不想污染主线 | 硬着头皮在主对话里问，或另开窗口 | 旁路开一个小对话，两边互不干扰 | 「提问不该有副作用」——**性质变了** |
+| 终端 | 跑一条命令 | 切到系统终端，常常还得先 `cd` | 右列里跑，工作目录天然就是对的 | 「命令的上下文应该跟着会话走」 |
+| 浏览器 / 预览 | 看这个页面出来是什么样 | 切浏览器标签，或手动打开产物 | 右列内嵌，当场看 | 「产出物要能当场验收」 |
+| **智能体** | 谁在替我干活、跑到哪了、哪个停了 | **基本没办法**——只能翻记录猜 | 主代理在最上，直系子代理一人一行，带运行/结束状态 | 「派了活之后，我要的是**扫一眼**，不是盯着守」（见 §四·洞察 4） |
+| **应用** | 这摊活到底是在哪儿干的 | **基本没办法**——靠脑子记或敲 `pwd` | 打开就看到当前会话锚定的工作区 | 「界面应该告诉我我在哪，而不是要我自己记住」 |
+| **画像** | 这个会话现在是什么状态 | 靠界面小细节猜（在跑？停了？哪一次？） | 标题 / 运行或空闲 / 工作区，写清楚 | 「离席回来，不用重建心智模型」 |
+
+连**顺序**都在讲同一件事：`10…50` 是操作面（看/改/查/问/跑/验），`60…70` 是态势面（谁在干、在哪儿干、什么状态）。
+先让"活能在这儿干完"，再让"我心里有数"——这是这个包对用户的两级承诺。
+
+## 四、深度分析：需求到底发生了什么变化
+
+### 洞察 0 · 官方原生假设"你只是看"，而真实使用是"在这儿干活"
+
+这是整个需求空间的起点。官方原生不是做得不好，而是**取向不同**：只读预览是"查看器"的思路，
+而使用者把它当"工位"用——他会在这里改一个文件、跑一条命令、瞄一眼改动。
+**当一块地方被当成工位，只读就会立刻变成绕路。** 这就是这个包存在的全部理由。
+
+### 洞察 1 · 从「只读」到「可写」：补的不是功能，是主权的归还
+
+官方只给预览，意味着**每一个"改一下"都要离开这块地方**。装上之后，改、查改动、跑、验四件事都在原地完成。
+用户省下的不是几次点击，而是**每次离开都要付出的"上下文重建"成本**——回来要重新找到刚才的位置、重新想起来自己在干嘛。
+需求因此从「我要能看」变成「我要在这儿把活干完」。
+
+### 洞察 2 · 「留在原地」会变成默认预期（棘轮效应）
+
+一旦右列里能改文件、能跑命令、能看预览，他对"跳出去一下"的容忍度会**永久下降**。
+他会开始说「为什么这个还要我切窗口？」——而这句话在他用官方原生时是说不出口的（因为原生本来就没有可切的东西）。
+**这类需求只前进、不后退**，所以值得一次做对：它一旦被填好，就变成基础设施。
+
+### 洞察 3 · 消除副作用之后，他会开始"问"（侧边对话）
+
+侧边对话的价值不在"多一个对话框"，而在**把提问的代价从"可能污染主线"降到"零"**。
+需求的性质变了：以前他的问题是「要不要问？」（一个决策），现在变成「顺手问一下」（一个动作）。
+**当一件事的代价趋近于零，用户的行为频率会跳一个数量级**——这是需求分析里最值得警惕、也最值得利用的一条规律。
+
+### 洞察 4 · 看得见 → 敢放手（智能体 tab 的核心价值）
+
+这是整个包里最值钱的一条。官方原生在这一点上是**彻底空白**：
+
+- 官方没有子代理视图，也没有任何"队伍"概念 → 他派了活之后**只能等**，或者不停往上翻记录确认；
+- 这个包的「子代理」让他能**进入**某一个；「智能体」让他**不必进去就看得到全局**——主代理 + 直系子代理，谁在跑、谁停了。
+
+用户真正的痛点不是"我进不去子代理"，而是**"我不敢派太多活"**：
+因为看不见，他只能用"盯着"来对冲风险，而盯着就失去了并行的意义。
+
+> **看得见 → 敢放手 → 真的并行 → 才配得上"多智能体"。**
+> 需求从「我要能看见」升级为「我要能放心」。
+
+### 洞察 5 · 心智模型从脑子里搬到界面上（应用 / 画像）
+
+多项目、多会话的人切换时要重建一次"我这是在哪儿"——标题差不多的会话最容易看错，
+而看错的代价是**写错文件**。官方原生在右列里一个字都不写这件事。
+「应用」「画像」做的就是**把这份"我记得"外化成"界面写着"**。
+需求的性质：从「我要记性好」变成「界面不该让我记」。
+
+### 洞察 6 · "引导页"第一次有了意义：从单一工具到工作台
+
+官方原生只有一个入口（Files），所以它**默认直接开文件树，罗盘界面根本不会出现**。
+入口一多，罗盘才登场——用户第一次能"一屏看见这块地方能干什么"。
+这是**用户层面的分水岭**：官方是"一个工具"，装了之后是"一个工作台的目录页"。
+（对照 §二那个细节：入口数决定了这块地方的形态。）
+
+### 洞察 7 · 价值随"并行度"放大；而成本几乎为零
+
+- 单会话、单项目的用户：「应用」「画像」几乎用不上，「智能体」也只有一个主代理；
+- 一旦同时开几个会话、派几个子代理、换几个项目：这三个 tab 的边际价值**陡增**。
+
+所以这套东西**不是人人需要，但接到的人离不开**。
+同时它**不新增数据源、不新增进程、不引入新的失败面**——只是把宿主已经投影出来的信息换个视角呈现
+（逐条列在 [03-功能说明](03-功能说明)）。对使用者意味着：**低风险地换到确定性**，这是它最该守住的边界。
+
+## 五、由以上分析推出的需求（U1–U6）
+
+| # | 需求（用户口吻） | 怎么算他满意了 | 现状 |
+| --- | --- | --- | --- |
+| U1 | 「我要在这儿把活干完，别老让我跳出去」 | 改文件、查改动、跑命令、看预览、顺手追问，都在右列完成 | ✅ 操作面六个 tab |
+| U2 | 「我要看得见谁在替我干活」 | 右列点一下就有队伍表；人数/状态一眼可辨；没有子代理时明确说"没有"，不是空白 | ✅ 智能体 tab |
+| U3 | 「我要知道我是在哪儿干的活、这会话什么状态」 | 打开就看到工作区与运行/空闲，不用敲 `pwd`；拿不到应用信息时如实说明 | ◑ 工作区/状态 ✅ · 应用层等宿主 |
+| U4 | 「我点开 HTML 就该看得见」 | 自包含 HTML 完整显示，而不是一行 `forbidden`；**但不许为此拆掉沙箱** | ✅（多文件需我本人点「临时解锁」） |
+| U5 | 「我的界面不许自己乱套」 | 右列只有一套侧边栏、一个开合入口；弹窗完整盖在面板之上、按钮点得到 | ✅ |
+| U6 | 「我敢升级，也退得回去」 | 有"宿主版本 ↔ 插件版本"对照表；每步升级都有分支/tag 可回滚 | ✅ 两条版本线；新宿主线待实机验证 |
+
+## 六、我们不做的事（省得期待错位）
+
+- **不重造官方已有的东西。** 官方给了容器与文件树，我们在它里面长东西，不另起一套侧边栏。
+- **不为"看得见"放宽安全边界。** 需要放宽必须由用户**本人显式点**「临时解锁」。
+- **不做团队/房间/多智能体协作编排。** 那是宿主的另一类职责。
+- **不承诺"装上立刻见效"。** 单会话用户可能几乎感觉不到差异（见洞察 7）。
+
+## 七、已知的「暂时满足不了」（诚实交代）
+
+| 他想要的 | 现状 | 为什么（一句话） | 何时会有 |
+| --- | --- | --- | --- |
+| 知道这摊活属于哪个**应用**、有哪些入口 | 「应用」只显示工作区 | 宿主目前没有向插件提供应用清单的通道 | 宿主提供 feed 后即可接上 |
+| 一次摊开**完整**子代理树（子代理的子代理） | 只显示**直系** | 宿主投影只给一层 | 同上 |
+| 沙箱状态下多文件 HTML 的相对资源 | 需点「临时解锁」 | 不透明源沙箱下子请求拿不到宿主信任头（安全边界的必然结果） | 不打算改——这是刻意保留的边界 |
+
+> 这三条说明同一件事：**需求跑在宿主能力前面**。写出来不是免责，是让读的人知道
+> "不能用"和"还没做"是两回事。
+
+## 附录 A · 证据与实现索引
+
+开发与排障看这里；其余读者可跳过。
+
+**"官方原生到底有什么"的证据**（本机宿主 `dsh@0.1.5-rc.2`，官方包自带文档）：
+
+- 容器：`@deepseek-ai/dsh-client-ui-sidebar-right/README.zh.md` —— 停靠面、两种形态、扩展席位、引导页。
+- 唯一的页：`@deepseek-ai/dsh-client-ui-sidebar-files/README.zh.md` —— "文件树 tab 类型……把文件打开到 Sidebar 里"。
+- 唯一的查看器：`@deepseek-ai/dsh-client-ui-sidebar-documentpreview/README.zh.md` —— "Sidebar tab 的 kind 为 `text`"，未知扩展名纯文本兜底。
+- "官方只有一个入口 ⇒ 罗盘不出现"：同上 sidebar-right 文档「引导页」一节。
+
+**本包一侧的对应实现**（`editor`/`git`/`subagent`/`sidechat`/`terminal`/`browser` 为随包操作面；
+`agents`/`apps`/`profile` 是本 fork 自增的态势面——对内维护用，对外它是一个包）：
+
+| 需求 | 机制（去哪看） | 关键证据 |
+| --- | --- | --- |
+| U5-a 右列只有一套侧边栏 | 每个 tab 注册成原生 tab 类型（`kind = descriptor.id`）渲染进官方右列；自绘面板已移除 | [02-系统架构](02-系统架构)、[05-运维手册](05-运维手册) |
+| U5-b 弹窗不被面板切 | 宿主容器上的层叠上下文（`isolation`）导致；挂载点改挂 `#root` 而不再挂 `document.body` | [06-故障排查](06-故障排查) |
+| U4 HTML 预览 | 主框架 `fetch` → `srcDoc`，**`sandbox` 属性未动**；失败回退路由 URL | [06-故障排查](06-故障排查) |
+| 与官方 `text` 预览的关系 | 本包的编辑器类型以更高优先级接管 `dsh-resource://file/**`，卸载即恢复官方预览 | `docs/external-plugin-guide.md` §「内置类型接管」 |
+| U6 版本线 | 宿主版本不匹配时宿主**静默禁用**整行（不报错、无日志）；`^` 跨 minor 判 false | [04-部署指南](04-部署指南)、[06-故障排查](06-故障排查) |
+
+<!-- 本页只讲"为什么需要"。实现细节、提交号、测试名一律留在 02–07 与附录索引里。 -->

docs/wiki/02-系统架构.md

@@ -0,0 +1,154 @@
+# 02 · 系统架构
+
+> 本篇说明插件的**分层、接口面、层叠契约与关键不变量**。
+> 与源码一一对应，可直接当作改动前的「雷区地图」使用。
+
+## 一、总体分层
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│ DSH 宿主（Desktop Electron 壳 / Web profile）                              │
+│  ├─ 原生右侧栏   ctx.sidebarRight / sidebarRightTabs（tab 类型注册表）       │
+│  ├─ 会话与任务   ctx.sessions.list（会话摘要、子代理、投影）、ctx.tools       │
+│  ├─ webServer    路由挂载点（插件用 /sidebar/* 前缀注册）                    │
+│  └─ 桌面壳层     webserver 外层的请求围栏 + #root 的 content-viewport 标记   │
+└───────────────┬──────────────────────────────────────────────────────────┘
+                │ ① 宿主 → 插件：cordis 服务注入（inject）
+                │ ② 插件 → 宿主：原生 tab / 资源打开 / 路由
+┌───────────────┴──────────────────────────────────────────────────────────┐
+│ 插件 HOST 半（Node，lib/index.js）                                         │
+│  · src/index.ts      路由注册（/sidebar/*）、信任围栏、会话/文件数据、HTML 交付 │
+│  · src/trust-fence.ts 请求信任围栏（Host 头 / 令牌）                         │
+│  · src/invariant.ts  依赖零的断言与 semver 工具（host/client 共用）           │
+└───────────────┬──────────────────────────────────────────────────────────┘
+                │ 浏览器侧模块（__ModuleLoader__ bundle，非 CJS）
+┌───────────────┴──────────────────────────────────────────────────────────┐
+│ 插件 CLIENT 半（浏览器，lib/client.js + 懒加载 chunk）                      │
+│  · src/client/index.tsx    应用入口：装配 store/service/原生适配/信息层       │
+│  · src/client/native/      原生右侧栏适配（tab 记录、tab 体、tab 芯片标题）    │
+│  · src/client/builtins/    内置面板：文件 / 文件变动 / 子代理 / 侧边对话 /     │
+│                            终端 / 浏览器 + 文件预览器                        │
+│  · src/client/sidebar/     自绘底部工作台与开合控件（原生侧边栏之外的部分）     │
+│  · src/client/apes/        信息层三 tab（本 fork 的增量）                     │
+│  · src/client/service.ts   ctx.betterSidebar 服务（供其他插件注册）            │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+## 二、构建产物
+
+| 产物 | 角色 | 备注 |
+| --- | --- | --- |
+| `lib/index.js` | host 半（ESM，Node） | 路由、围栏、数据面 |
+| `lib/invariant.js` | 不变量面（零依赖） | host/client 都要 import，**不得**引入 Node 内置或宿主包 |
+| `lib/client.js` | client 主 bundle | 浏览器 `window.__ModuleLoader__.load({...})` 形态，**不是** CJS/ESM，Node 里 `require` 会因 `window is not defined` 抛错 |
+| `lib/client-registry.js` | 懒加载 chunk | 高开销能力（图标/预览库）按需加载 |
+| `lib/client-editor.js` | 懒加载 chunk | 编辑器（CodeMirror 系） |
+| `lib/client-locale.js` | 懒加载 chunk | 语言包 |
+| `lib/client-mermaid.js` | 懒加载 chunk | Mermaid 渲染 |
+| `lib/client-terminal.js` | 懒加载 chunk | 终端 |
+| `lib/types/**/*.d.ts` | 类型声明 | 供消费方类型检查 |
+
+> 懒加载动机：主 bundle 不应静态 import 重型预览库；chunk 通过宿主 `ctx.modules` 解析外部依赖
+> （入口在 `src/client/index.tsx` 里先 `setChunkModuleSystem(ctx.modules)`）。
+
+## 三、三层接口面
+
+### 3.1 宿主 → 插件（cordis 注入）
+
+```ts
+// src/index.ts
+export const name = 'dsh-apes-sidebar'
+export const inject = ['webServer', 'sessions', 'webRuntime', 'tools']
+export function apply(ctx: Context, config?: SidebarConfig): void
+```
+
+客户端侧读取的宿主面（结构化镜像，运行时由宿主提供）：
+`ctx.sessions.list`（`getSnapshot/subscribe`）、`ctx.sidebarRight`（原生右列与 `openResource`）、
+`ctx.slots`、`ctx.settings`（挂载行 `config`）、`ctx.modules`（懒加载 chunk 的模块系统）。
+
+### 3.2 插件 → 宿主
+
+| 方向 | 手段 |
+| --- | --- |
+| 注册 tab 类型与 tab 体 | `src/client/native/registerNativeSurface()` → 原生右侧栏注册表 |
+| 打开会话内文件 | `ctx.sidebarRight.openResource('dsh-resource://file/…')` |
+| 暴露 HTTP 能力 | `/sidebar/` 前缀路由：`api` · `file` · `html` · `upload` · `ws/terminal` · `ws/agent-opens` · `ws/agent-terminals` |
+
+### 3.3 插件 → 其他插件（对外服务）
+
+`ctx.betterSidebar`（`src/client/service.ts`）对外开放 `registerTab` / `registerFileViewer` 等，
+并按「能力清单」做前向兼容门控（能力只增不减）。对外契约见仓库内
+[docs/external-plugin-guide.md](../blob/main/docs/external-plugin-guide.md)。
+服务版本常量 `SIDEBAR_SERVICE_VERSION` 必须与 `package.json` / `dsh.plugin.json` 的版本三方一致
+（有单元测试断言这一对）。
+
+## 四、面板宿主与层叠契约（重点雷区）
+
+插件的所有面板渲染在一个 **body 级（或壳层 viewport 级）的宿主层**里：
+
+```css
+[data-dsh-panel-host] { position: fixed; inset: 0; z-index: 25; pointer-events: none }
+```
+
+`z-index: 25` 不是随手取的，它要同时满足：**在 app 内容与壳层 overlay 之上、在宿主交给插件用的
+overlay 槽之下**。完整取义：
+
+| 层级 | 对象 |
+| --- | --- |
+| `z-index: auto` | app 的流内内容、`.dshDesktopFrame` |
+| **25** | **本插件的面板宿主** |
+| 30 | 宿主的动态插件面板（ui-cordis） |
+| 100+ | app 的 overlay 栈（Toast / onBoarding 等） |
+| 1000 | `.dshDesktopOverlay[data-shell-overlay]`（宿主给 `shell.overlay` 槽的容器，第三方弹窗在此） |
+
+**陷阱（已修，`4422001`）**：DSH 桌面壳的有框模式会给上游 `#root` 打标
+`data-dsh-desktop-content-viewport` 并施加 `isolation: isolate`，使 `#root` 成为一个**层叠上下文**。
+宿主自己的 overlay 层就在这个上下文内；若插件宿主挂在 `document.body`（上下文之外），
+它是「带正 z-index 的定位元素」，会画在整个上下文**之上**——把宿主 overlay 里的弹窗（如社区插件市场）盖住。
+
+```ts
+// src/client/desktop-env.ts —— 修法：挂进壳层的 content viewport
+export function panelHostParent(doc: Document = document): HTMLElement {
+  return doc.querySelector<HTMLElement>('#root[data-dsh-desktop-content-viewport]') ?? doc.body
+}
+```
+
+进入该上下文后，25 恢复原意（在 app frame 之上、在 overlay 层 1000 之下）；无该标记的部署
+（纯网页 / 未打标的壳）仍挂 `document.body`，行为不变。重新锚定守卫同时监听
+`document.body` 的 `data-dsh-desktop-mode`（壳层打标与它是同一个 effect），因此壳层在插件挂载**之后**
+才框住 `#root` 的情况也能被搬到正确位置。
+
+## 五、数据流示例
+
+**会话 → 信息层**
+
+```
+ctx.sessions.list.getSnapshot()      →  { byId, projectionsBySession? }
+  useSyncExternalStore(subscribe)        （uSES 安全订阅）
+  ├─ apes:agents  → rootAncestor(byId, scope.sessionId) 找主代理
+  │                 → projectionsBySession[rootId].values.subagentCatalog 取直系子代理
+  │                   （无投影时回退 byId 里的 durable 子会话）
+  └─ apes:profile / apes:apps → byId[scope.sessionId]（标题 / cwd / running）
+```
+
+**文件 → 预览**（HTML 为例）
+
+```
+编辑器/diff 面板 → /sidebar/html/<session>/<path>    （路由负责路径围栏与体积上限）
+  主框架 fetch 取回文档文本 → 注入 <base href="<该文件的路由目录>">
+  → iframe srcDoc + sandbox（不透明源）
+  取失败时回退为 iframe src=路由 URL，把路由的答复原样透出
+```
+
+## 六、关键不变量（改动前必读）
+
+1. **host / client 拆分是结构性的**：client bundle 在浏览器运行，不得 import Node 内置；
+   `src/invariant.ts` 两侧共用，必须保持零依赖。
+2. **`dsh-better-sidebar` 是 peer，永不打包**：一旦被内联，client 会带上第二份侧边栏注册表，
+   tab 注册进死实例，界面上永不出现。
+3. **tab id 前缀归本 fork**：信息层用 `apes:*`；不得占用上游/宿主内部 id。
+4. **HTML 预览的沙箱令牌不得放宽**（不加 `allow-same-origin` 等）；交付方式只能是「主框架取文档 + `srcDoc`」。
+5. **颜色只用宿主设计令牌**（`--dsw-alias-*`），不写硬编码色值；几何量（字号/间距/圆角）无公开令牌，内联即可。
+6. **所有面向用户的字符串走 i18n**，`zh` / `en` 必须同时存在。
+7. **变更后必须重新同步到 profile**：构建产物非字节确定性，且 profile 的 `file:` 依赖是复制语义，
+   不能假定旧副本可用（见 [04-部署指南](04-部署指南)）。

docs/wiki/03-功能说明.md

@@ -0,0 +1,109 @@
+# 03 · 功能说明
+
+> 本篇是**功能清单与行为契约**：有哪些面板、数据从哪来、文案与配色怎么走、安全边界在哪、能配什么。
+
+## 一、面板与标签页总表
+
+「来源」列：**上游** = 来自 `dsh-better-sidebar`；**宿主** = DSH 自身提供并占用该槽位；**本 fork** = 本项目的增量。
+
+| id | 名称 | order | 来源 | 数据 / 行为 |
+| --- | --- | --- | --- | --- |
+| `editor` | 文件 | 10 | 上游 | 文件树 + 编辑器（CodeMirror 系，懒加载 `client-editor`） |
+| `git` | 文件变动 | 20 | 上游 | 工作区变更、单个 diff 视图 |
+| `subagent` | 子代理 | 30 | 上游 | 会话的子代理视图 |
+| `sidechat` | 侧边对话 | 35 | 上游 | 会话内旁路对话 |
+| `terminal` | 终端 | 40 | 上游 | PTY 终端（懒加载 `client-terminal`；v0.24.1 线起由宿主内置终端承担） |
+| `browser` | 浏览器 | 50 | 上游 | 内嵌浏览器/HTML 预览宿主 |
+| `diff` | （内部） | -1 | 上游 | 非用户可见，供内部打开 diff |
+| **`apes:agents`** | **智能体** | **60** | **本 fork** | 主代理 + 直系子代理拓扑 |
+| **`apes:apps`** | **应用** | **65** | **本 fork** | 当前会话所属工作区（宿主暂无「应用」feed） |
+| **`apes:profile`** | **画像** | **70** | **本 fork** | 当前会话摘要（标题 / cwd / 运行态） |
+
+> order 10–50 是上游/宿主既定带宽，apos 信息层取 60/65/70 留出余量，避免与原生面板抢占位置。
+
+## 二、信息层三 tab（本 fork 的增量）
+
+三个 tab 全部是**单实例**（`single: true`），且都按 DSH 标准 `TabDescriptor` 注册，
+因此自动获得原生侧边栏的全部待遇：进入原生 guide、tab 芯片带图标、可开合与分栏。
+
+| tab | 展示内容 | 数据来源 | 空态 |
+| --- | --- | --- | --- |
+| `apes:agents` | 根（主代理）卡片 + 其直系子代理卡片；每行显示标签、`one-shot`/`continuable`、运行态圆点 | ① `ctx.sessions.list` 的 `byId`（durable 会话摘要）；② 宿主的会话投影 `projectionsBySession[sessionId].values.subagentCatalog`（直系子代理清单） | 「当前会话没有子代理」提示 |
+| `apes:apps` | 当前会话的工作区（cwd） | `byId[scope.sessionId].cwd`，回退 `scope.cwd` | 明确写出「宿主今日无应用 feed」 |
+| `apes:profile` | 会话标题、运行/空闲、cwd | `byId[scope.sessionId]` | 「无 cwd」提示 |
+
+**实现要点**：两个来源被归一化成同一种行形状 `{ id, label, mode }`，**活动态统一从 `byId` 读**，
+于是「投影已就绪」与「仅有 durable 摘要」两种情况下渲染一致；这也是上游 0.1.6→0.1.7 会话 feed
+迁移（`subagentsByParent` → `projectionsBySession`、`list.current` 删除）后的落地方式。
+
+## 三、文件预览器
+
+| id | 适用 | 说明 |
+| --- | --- | --- |
+| `image` | 图片 | 走媒体路由，受 `mediaLimit` 限制 |
+| `pdf` | PDF | 内嵌查看 |
+| `markdown` | Markdown | 渲染（Mermaid 走懒加载 chunk，可手动刷新） |
+| `html` | HTML | **不透明源沙箱 iframe**，见下节 |
+| `code` | 代码 | 高亮查看（编辑器懒加载） |
+| `binary-download` | 二进制 | 只提供下载 |
+
+### 3.1 HTML 预览的交付方式（重要）
+
+```
+路由 /sidebar/html/<session>/<path>    ← 路径围栏 + 体积上限（readLimit）
+        │
+        ├─ 主框架 fetch（唯一同时被宿主围栏信任、又能带上 Electron 头的角色）
+        │
+        ├─ 注入 <base href="<该文件的路由目录>">   ← 让 ./style.css 等相对引用解析回本文件所在目录
+        │
+        └─ iframe srcDoc=<文档> + sandbox=HTML_IFRAME_SANDBOX
+```
+
+| 状态 | 自包含 HTML | 多文件 HTML（外链 CSS/JS/图片） |
+| --- | --- | --- |
+| 沙箱态（默认） | ✅ 完整可用 | 正文可用，**相对资源不可用**（iframe 源为 `null`，子请求同样被宿主围栏拒绝） |
+| 临时解锁（无 sandbox 属性） | ✅ | ✅ **相对资源可用**（iframe 继承 GUI 源，成为普通同源请求） |
+
+设计取舍：**沙箱令牌一个字符都不放宽**。多文件 HTML 想要完整效果需用户显式点「临时解锁」——
+这是把「放宽边界」的决定权留给用户的显式动作，而不是插件默认降级。
+
+## 四、安全边界（三层）
+
+| 层 | 机制 | 说明 |
+| --- | --- | --- |
+| 预览内容 | `sandbox="allow-scripts allow-popups allow-downloads allow-modals"` | **不含 `allow-same-origin`**：预览文档运行在不透明源里。宿主路由另有 CSP `sandbox` 兜底 |
+| 插件路由 | 请求信任围栏（`src/trust-fence.ts`） | 校验 Host 头/令牌，拒绝跨站或非授权来源对 `/sidebar/*` 的访问 |
+| 桌面壳 | Electron 注入的 `x-dsh-desktop-renderer` 头 | 扩展模式下所有路由的前置围栏；只发给主框架与同源子框架。这正是「沙箱 iframe 发不出请求」的根源 |
+
+## 五、i18n 与主题
+
+- **语言包**：`src/client/locales.ts` + 19 个 `src/client/locales-*.ts` 覆盖文件；默认 `zh`，缺省回退 `en`。
+- **本 fork 文案**：集中在 `src/client/apes/locales.ts`，每个 key 同时提供 `zh` / `en`。
+- **硬性约定**：界面里**不得出现裸字符串**，一律 `t('key')`。
+- **配色**：只用宿主设计令牌 `--dsw-alias-*`（bg / border / label / state / interactive 系列），
+  写法为 `var(--dsw-alias-xxx, <字面回退>)`，保证在非 DSH 环境（单元测试）也能渲染。
+  **无公开的 `--ds-*` 几何令牌**，字号/间距/圆角内联即可。
+
+## 六、配置面（挂载行 `config`）
+
+配置写在插件挂载行上（profile 的 `cordis.patch.yml` 或 bundle patch 的 insert 行），设置页写的也是它：
+
+| 字段 | 默认 | 含义 |
+| --- | --- | --- |
+| `readLimit` | `512 KiB` | 单文件读取上限（超出截断并标记 `truncated`） |
+| `mediaLimit` | `20 MiB` | 媒体（图片等）读取上限 |
+| `uploadLimit` | `128 MiB` | 上传上限 |
+| `listLimit` | `1000` | 目录列举条目上限 |
+| `terminalsPerSession` | `3` | 每会话终端数上限 |
+| `shell` / `shellArgs` | 自动解析 | 终端 shell 与其启动参数（`shellArgs` 非空时替换默认 `-l`） |
+
+例：在挂载行里指定 shell
+
+```yaml
+- insert:
+    - id: better-sidebar
+      name: 'dsh-apes-sidebar'
+      config:
+        shell: /bin/zsh
+        shellArgs: ['--noprofile', '--no-rc']
+```

docs/wiki/04-部署指南.md

@@ -0,0 +1,163 @@
+# 04 · 部署指南
+
+> 目标：在一台机器上把本插件挂进 DSH，并确认它**真的在跑**。
+> 关键前提：**先确认宿主版本，再选版本线**——选错线的唯一症状是「静默失效」。
+
+## 一、前置条件
+
+| 项 | 要求 |
+| --- | --- |
+| Node | ≥ 20（`engines.node`）；本机验证用 22.x |
+| pnpm | 11.x（`pnpm install` 会自动触发 `prepare: tsdown` 构建） |
+| DSH | 见下面的版本矩阵 |
+| 终端可用性 | 仅 v0.19.1 线需要额外放行 `node-pty` 原生构建（见 §五） |
+
+### 1.1 宿主版本矩阵（先读这张表）
+
+| 版本线 | 分支 | 插件版本 | peer 声明 | 适用宿主 |
+| --- | --- | --- | --- | --- |
+| 旧宿主线 | `main` | 1.2.0 | `^0.1.5-rc.1` | DSH `0.1.5-rc.1+`（含 `0.1.5-rc.2`，即 **DSH Desktop 2.0.10** 内置版本） |
+| 新宿主线 | `sync/v0.24.1` | 1.3.0 | `^0.2.0-rc.1` | DSH `0.2.0-rc.1+` |
+
+**怎么查宿主版本**（扩展模式桌面版）：
+
+```bash
+# 内置的 dsh 版本
+grep -m1 '"version"' "/Applications/DSH Desktop.app/Contents/Resources/app/node_modules/@deepseek-ai/dsh/package.json"
+# 或看 profile 里装的宿主包
+grep -m1 -A2 '"@deepseek-ai/dsh"' ~/.dsh/profiles/desktop/package.json
+```
+
+**选线决策**
+
+```
+宿主 ≥ 0.2.0-rc.1 ? ── 是 ──▶ sync/v0.24.1（1.3.0）
+                    └─ 否 ──▶ main（1.2.0）
+```
+
+> ⚠️ **peer 不匹配不会报错。** 宿主以 `semver.satisfies(host, peerRange, { includePrerelease: true })` 预检，
+> caret 跨 minor 判 false 后**整行静默禁用**：不加载、无日志、界面上「像没装」。
+> 因此「装完没反应」的第一件事永远是核对宿主版本 ↔ peer 范围。
+
+## 二、安装方式（本 fork 未发布 npm 包）
+
+`npm view dsh-apes-sidebar` 返回 404 —— **本 fork 不在 npm 上**（README 里的 npm 徽章/命令是沿用上游文档）。
+实际部署使用「本地源码 + `file:` 链接依赖」：
+
+### 步骤 1：构建
+
+```bash
+cd <插件仓库绝对路径>
+git checkout main            # 或 sync/v0.24.1（按宿主版本选）
+pnpm install                 # 会顺带跑 prepare: tsdown
+pnpm typecheck && pnpm build && pnpm test    # 门禁三连
+```
+
+产物（`lib/`）：`index.js` / `invariant.js`（host）+ `client.js` + 懒加载 chunk
+（`client-registry` / `client-editor` / `client-locale` / `client-mermaid` / `client-terminal`）+ `types/`。
+
+### 步骤 2：接进 profile
+
+编辑 `~/.dsh/profiles/<profile>/package.json`（桌面版为 `desktop`，网页版通常为 `web`）：
+
+```jsonc
+{
+  "dependencies": {
+    "dsh-apes-sidebar": "file:/绝对路径/dsh-apes-sidebar"   // ← 必须是绝对路径
+  },
+  "dsh": {
+    "profile": {
+      "bundles": [
+        "…",
+        "dsh-apes-sidebar"                                   // ← 加入 bundle 栈
+      ]
+    }
+  }
+}
+```
+
+> 也可以在 profile 自己的 `cordis.patch.yml` 里手写挂载行（老方式）。**两种方式不要同时用**：
+> 会双挂载成两个 Node 半、两个侧边栏。包内自带的 `cordis.patch.yml` 是 `dsh.bundle.patch` 层，
+> 由官方 CLI 安装时自动追加 bundle，并带「聚合包双挂载退让」守卫。
+
+### 步骤 3：让 profile 重新安装依赖
+
+```bash
+cd ~/.dsh/profiles/<profile> && pnpm install
+```
+
+**为什么必须重装**：pnpm 对 `file:` 依赖是**复制**语义（不是软链）。源码 `pnpm build` 之后，
+profile 的 `node_modules/dsh-apes-sidebar/lib` **仍是旧副本**——这就是「改了代码但界面没变」的头号原因。
+DSH 启动时也会 reconcile profile 的 pnpm workspace，但不要假定它一定帮你刷新。
+
+### 步骤 4：完整重启
+
+**⌘Q 完全退出 DSH，再重新启动**（不是关窗口）。client 半有热加载，但 host 半与依赖变更必须走完整重启。
+
+## 三、验收清单
+
+重启后逐条核对（每条都对应一个可观察事实）：
+
+- [ ] **右列只有一套侧边栏**、一个开合控件（不再出现自绘的第二套开关）
+- [ ] 原生 guide 里能看到本插件的 tab 芯片，且**带图标**
+- [ ] 三个信息层 tab 存在：**智能体 / 应用 / 画像**（order 在原生面板之后）
+- [ ] `apes:agents` 打开后：有主代理卡片；有子代理时列出直系子代理（标签 + 模式 + 运行态）
+- [ ] 打开一个 HTML 文件：**沙箱态下自包含 HTML 能正常渲染**（不再是 `forbidden`）
+- [ ] 打开「社区插件市场」：弹窗**完整盖在**本插件面板之上（面板不切弹窗角）
+- [ ] 页面左下角**没有**红色诊断条（有的话说明 client 生命周期某处抛错）
+- [ ] 开发者控制台**没有** `[dsh-apes-sidebar] … error` 前缀的错误
+
+## 四、网页 profile 与桌面 profile 的差异
+
+| 项 | 桌面版（DSH Desktop） | 网页版 |
+| --- | --- | --- |
+| profile 目录 | `~/.dsh/profiles/desktop` | 通常 `~/.dsh/profiles/web` |
+| 外壳 | Electron 壳，有「扩展模式/兼容模式」与请求围栏 | 浏览器直连宿主端口 |
+| 预览 iframe | 受渲染器围栏约束（因此必须走 `srcDoc` 交付） | 无该围栏，但仍受路由 CSP/沙箱约束 |
+| 面板宿主层级 | 壳层会给 `#root` 打 content-viewport 标记 → 宿主挂进 `#root` | 无标记 → 宿主挂 `document.body` |
+| 刷新方式 | ⌘Q 完整退出再启动 | 硬刷新（Cmd/Ctrl+Shift+R） |
+
+## 五、v0.19.1 线特有：放行 node-pty 原生构建
+
+`main`（上游 v0.19.1 基线）在 `package.json` 中仍有 `node-pty` 依赖；pnpm 11 默认**拦截依赖的构建脚本**，
+于是首次安装会失败或终端不可用：
+
+```bash
+cd ~/.dsh/profiles/<profile>
+pnpm approve-builds        # 选中 node-pty，回车确认
+pnpm rebuild node-pty      # 必要时
+```
+
+`sync/v0.24.1`（1.3.0）**不含** `node-pty`（终端交由宿主内置承担），无需此步。
+（`main` 与 `sync/v0.24.1` 的 `node-pty` 引用数：1 / 0。）
+
+## 六、切换与卸载
+
+同一条线只能装一个（两条线都注册 `ctx.betterSidebar`，entry id 冲突，第二个被丢弃）。
+仓库自带切换脚本：
+
+```bash
+bash scripts/switch.sh --status        # 只看当前是哪条线
+bash scripts/switch.sh aps             # 切到本 fork 线（本地 file: 安装）
+bash scripts/switch.sh upstream        # 切回上游 dsh-better-sidebar
+bash scripts/switch.sh upstream 0.18.0 # 指定上游版本
+bash scripts/switch.sh aps --profile web   # 指定 profile
+```
+
+**完全卸载**：从 profile 的 `dependencies` 与 `dsh.profile.bundles` 中移除 `dsh-apes-sidebar`，
+`pnpm install`，⌘Q 完整重启。若曾手写过 `cordis.patch.yml` 挂载行，一并删除（否则会留下悬空 entry）。
+
+> 若同时装了聚合包（如 `@linxin666/dsh-web-ui-all`）且它内部也挂载了本包，
+> 包内 bundle patch 的守卫会让**本行退让**；此时请确认聚合包在 bundle 栈中位于本行之前。
+
+## 七、变更后的重新部署
+
+```bash
+# 插件仓库
+pnpm typecheck && pnpm build && pnpm test
+# profile
+cd ~/.dsh/profiles/<profile> && pnpm install
+# ⌘Q 退出 DSH 再启动
+```
+
+改完代码**必须**走完这三步：产物构建非字节确定性，profile 的 `file:` 副本也不会自动跟随。

docs/wiki/05-运维手册.md

@@ -0,0 +1,133 @@
+# 05 · 运维手册
+
+> 本篇是**日常运维、升级与回滚**的操作手册。所有命令都以「先留锚点、再动手、改完回读验证」为原则。
+
+## 一、版本线与分支策略（当前远端实况）
+
+| ref | 指向 | 含义 / 用途 |
+| --- | --- | --- |
+| `main` | `4422001` | **旧宿主线**：插件 1.2.0，上游基线 v0.19.1，peer `^0.1.5-rc.1`。本机 DSH Desktop 2.0.10 正在跑这条 |
+| `sync/v0.24.1` | `e5bbef1` | **新宿主线**：插件 1.3.0，上游基线 v0.24.1，peer `^0.2.0-rc.1`。待 ≥0.2.0 宿主实机验证 |
+| `backup/pre-sync-v0.19.1` | `96cc334` | v0.19.1 re-base **之前**的状态（旧 fork 三角色 tab 版） |
+| `backup/pre-sync-v0.24.1` | `4422001` | v0.24.1 re-base 之前的 `main`（等价于当前 main，作为下次升级的锚点） |
+| `tags/apes-v1.1.0-pre-sync` | `96cc334` | 与上面第一支 backup 同一提交，tag 形式的锚点 |
+| `tags/apes-v1.2.0` | `4422001` | 当前已验收的 1.2.0 线 |
+
+**纪律**：任何 re-base / 大改之前，先建 `backup/pre-sync-<新基线>` 分支 + `apes-v<版本>` tag，
+并**推送**到远端（本地锚点在多人/多机场景等于不存在）。
+
+## 二、回滚剧本
+
+### 场景 A：某次提交引入回归（单点回退）
+
+```bash
+cd <插件仓库>
+git log --oneline -5                 # 定位可疑提交
+git revert <sha>                     # 保留历史的回退（推荐）
+# 或整体丢弃：git reset --hard <上一提交>
+pnpm typecheck && pnpm build && pnpm test
+cd ~/.dsh/profiles/<profile> && pnpm install   # file: 是复制语义，必须重装
+# ⌘Q 完全退出 DSH → 重启
+```
+
+### 场景 B：整条线回退（例如新线在真机上不可用）
+
+```bash
+git checkout main                    # 或 backup/pre-sync-v0.24.1
+pnpm install && pnpm build
+cd ~/.dsh/profiles/<profile> && pnpm install
+# ⌘Q 重启
+```
+
+### 场景 C：profile 依赖/config 被改坏
+
+```bash
+cd ~/.dsh/profiles/<profile>
+cp package.json package.json.bak.$(date +%s)     # 先备份
+bash <插件仓库>/scripts/switch.sh aps            # 或 upstream，脚本会重写依赖与 bundle 行
+pnpm install
+# ⌘Q 重启
+```
+
+**回滚验收**：重启后按 [04-部署指南](04-部署指南) §三 的验收清单逐条核对（至少「右列一套侧边栏」
+与「三个信息层 tab 存在」两条）。
+
+## 三、发布 / 变更纪律
+
+1. **版本三元组必须一致**：
+   - `package.json` 的 `version`
+   - `dsh.plugin.json` 的 `version`
+   - `src/client/service.ts` 的 `SIDEBAR_SERVICE_VERSION`
+   三者不一致会被单元测试（`tests/service.spec.ts`）直接拦下——**不要改其中一个而忘了另一个**。
+2. **门禁三连必过**：`pnpm typecheck && pnpm build && pnpm test`。当前基线：`main` 131 个测试文件 /
+   1367 通过；`sync/v0.24.1` 141 个文件 / 1515 通过（另有 9 个 skip）。
+3. **产物非字节确定性**：两次构建的字节数可能相同但 **sha 不同**。因此「改完代码 → 让 profile 用旧副本」
+   永远不成立；必须重新 `pnpm build` + 让 profile 重新安装。
+4. **发布方式**：本 fork 未发布 npm 包，发布 = 推分支/tag + 目标机器 `git fetch && checkout && pnpm build`
+   + profile 重装。发布前把 `README.md` 与 `docs/wiki/` 一并更新（wiki 见 §六）。
+5. **不要顺手改无关文件**：re-base 时保持「只带自己的增量」，避免下次升级冲突面扩大。
+
+## 四、日常巡检清单
+
+| 频率 | 检查项 | 命令 / 判据 |
+| --- | --- | --- |
+| 每次部署后 | 版本三元组一致 | 见 §三.1 |
+| 每次部署后 | 产物标记齐全 | `grep -c 'apes:agents' lib/client.js`（>0）、`grep -c 'dsh-desktop-content-viewport' lib/client.js`（>0） |
+| 每次部署后 | profile 副本已刷新 | 比对 `lib/client.js` 与 `~/.dsh/profiles/<p>/node_modules/dsh-apes-sidebar/lib/client.js` 的 sha256 |
+| 每次升级宿主/插件 | 宿主版本 ↔ peer 范围 | 见 [04-部署指南](04-部署指南) §1.1（不匹配 = 静默禁用） |
+| 每月/大改前 | 锚点是否已推远端 | `git ls-remote <remote> \| grep -E 'heads/(main\|sync)\|tags/apes'` |
+| 异常时 | 诊断条与控制台 | 页面左下角红条；控制台 `[dsh-apes-sidebar]` 前缀 |
+
+## 五、备份与配置铁律
+
+- **改任何 profile 配置前先备份**，改完**回读验证**（不要假定写入即生效）：
+
+  ```bash
+  cp ~/.dsh/profiles/<profile>/package.json{,.bak.$(date +%s)}
+  # 改完：
+  python3 -c "import json;json.load(open('$HOME/.dsh/profiles/<profile>/package.json'));print('JSON OK')"
+  ```
+
+- **DSH 应用配置的类型陷阱**：部分字段（如材质/透明度类的 `macosMaterial`）必须是**字符串**
+  （`"off"` / `"transparent"`）。若被写成 YAML 布尔（`false`），DSH 会启动进**恢复模式**。
+  改完务必回读校验类型：
+
+  ```bash
+  python3 -c "import yaml;d=yaml.safe_load(open('$HOME/.dsh/settings.yaml'));v=d.get('macosMaterial');print(v, type(v).__name__)"
+  ```
+
+- **不要回滚/手工编辑** profile 的 `pnpm-lock.yaml`：由 pnpm 重建；手工改会导致解析错乱。
+- **凭据不进仓库**：远端推送用系统凭据助手（`git credential fill`），仓库内不写 token。
+
+## 六、百科（wiki）本身的维护
+
+百科源文件版本化在仓库 `docs/wiki/`，通过脚本推送到 Gitea wiki：
+
+```bash
+bash scripts/push-wiki.sh            # 推送/更新全部页面（幂等：有则 PATCH，无则 POST）
+bash scripts/push-wiki.sh 05-运维手册 # 只推一页
+```
+
+凭据来自 `git credential fill`（与推送代码同一套，不落盘）。修改文档的推荐流程：
+**改 `docs/wiki/*.md` → 提交到仓库 → 跑脚本推送**，这样 wiki 与代码同源可回溯。
+
+## 七、诊断与日志
+
+| 信号 | 含义 | 位置 |
+| --- | --- | --- |
+| 左下角红色诊断条 `[dsh-apes-sidebar] <phase> error: …` | client 生命周期某阶段抛错（mount / native / 懒加载等） | 页面左下角（`z-index: 2147483000`），同时 `console.error` 打前缀 |
+| 控制台 `[dsh-apes-sidebar] …` | 同上，且带上具体阶段名 | 开发者工具 Console |
+| 「插件像没装」且**无任何日志** | 宿主兼容性预检失败（peer 不匹配）→ **静默禁用** | 只能靠版本矩阵排查，见 [06-故障排查](06-故障排查) §1 |
+| 界面正常但面板层级错乱 | 面板宿主挂载点/层叠上下文问题 | 见 [02-系统架构](02-系统架构) §四 |
+
+## 八、性能与容量
+
+| 项 | 观察值 | 说明 |
+| --- | --- | --- |
+| `lib/client.js` | ≈ 0.9 MB | 主 bundle，始终加载 |
+| `lib/client-mermaid.js` | ≈ 7 MB（+12 MB map） | 懒加载，仅在需要渲染 Mermaid 时拉取 |
+| `lib/client-editor.js` | ≈ 2 MB | 懒加载，仅打开编辑器时 |
+| `lib/client-terminal.js` | ≈ 0.5 MB | 懒加载，仅打开终端时 |
+| 全量测试 | 约 3–4 分钟 | 变更后按需跑全量，日常可只跑相关 spec |
+
+主 bundle 不应静态引入上述重型库；新增重型依赖一律走 `src/client/chunks/`（懒加载 chunk）。

docs/wiki/06-故障排查.md

@@ -0,0 +1,208 @@
+# 06 · 故障排查
+
+> 每条都给出**症状 → 根因（机制）→ 处置 → 验证**。标注 ✅ 的条目是在真机上定位并验证过的案例。
+
+## 速查表
+
+| 症状 | 最可能根因 | 跳到 |
+| --- | --- | --- |
+| 装完「像没装」，界面无变化且**无任何日志** | peer 范围与宿主版本不匹配 → 静默禁用 | §1 |
+| 页面出现**两个侧边栏** / 两套开合按钮 | 双挂载（两条线同装，或残留挂载行） | §2 |
+| HTML 预览只显示 `forbidden` | 桌面壳渲染器围栏 + 不透明源 iframe | §3 |
+| 插件面板盖住宿主/第三方弹窗（如插件市场） | 面板宿主挂在层叠上下文之外 | §4 |
+| 终端打不开 / `node-pty` 加载失败 | pnpm 拦截原生构建（仅 v0.19.1 线） | §5 |
+| 改了代码，界面没变 | 产物未重建 / profile 副本未刷新 / 浏览器缓存 | §6 |
+| DSH 拒绝加载插件、entry pending | 插件声明（`dsh.plugin.json` / bundle patch）不合法 | §7 |
+| DSH 启动进**恢复模式** | profile 配置被写成错误类型（如 YAML 布尔） | §8 |
+
+---
+
+## §1 装完「像没装」：静默禁用 ✅
+
+**症状**：profile 里依赖装了、文件也在，但界面没有任何变化；日志里也没有插件相关报错。
+
+**根因**：宿主启动时做兼容性预检，判定 `peerDependencies` 与自身版本是否满足：
+
+```
+semver.satisfies(hostVersion, peerRange, { includePrerelease: true })
+```
+
+caret 范围**跨 minor 必然为 false**（例如 `^0.1.5-rc.1` 对 `0.2.0`）。判定失败后宿主的处理是
+**跳过这一行**——不抛错、不打日志、不加载。
+
+**处置**：核对宿主版本，改用匹配的版本线（见 [04-部署指南](04-部署指南) §1.1）。
+
+```bash
+grep -m1 '"version"' "/Applications/DSH Desktop.app/Contents/Resources/app/node_modules/@deepseek-ai/dsh/package.json"
+grep -n 'dsh-client-ui-sidebar-right' <插件仓库>/package.json     # 看 peer 范围
+```
+
+**验证**：重启后右列出现插件 tab；`lib/client.js` 里能 grep 到 `apes:agents`。
+
+**教训**：这一条没有日志可查，因此**部署前先看版本矩阵**是唯一可靠的预防手段。
+
+## §2 两个侧边栏 / 两套开合按钮 ✅
+
+**症状**：窗口里出现两套右侧面板与两组开合控件。
+
+**根因**：两个方向都可能：
+1. **旧版遗留**：v0.18.0 基线时插件自绘右侧面板与开关（`toggleCluster`）。升级后自绘部分应已移除。
+2. **双挂载**：同一条线被挂两次（profile 自己的 `cordis.patch.yml` 里还留着旧挂载行，
+   与 bundle patch 同时生效），或者本 fork 线与上游线同时安装（两者都注册 `ctx.betterSidebar`，
+   entry id 冲突，第二个被丢弃）。
+
+**处置**：
+
+```bash
+# 确认产物里已经没有自绘开关
+grep -c toggleCluster <插件仓库>/lib/client.js        # 期望 0
+
+# 检查是否双挂载：profile 里是否同时存在 bundle 行 与 手写挂载行
+grep -n "dsh-apes-sidebar\|dsh-better-sidebar" ~/.dsh/profiles/<profile>/cordis.patch.yml ~/.dsh/profiles/<profile>/package.json
+```
+
+- 有残留手写挂载行 → 删除它，只保留一条通道。
+- 两条线同装 → `bash scripts/switch.sh aps`（或 `upstream`）二选一。
+- 装了聚合包（如 `@linxin666/dsh-web-ui-all`）→ 确认聚合包在本包之前，让包内守卫生效。
+
+**验证**：右列只剩一套面板与一个开合控件。
+
+## §3 HTML 预览显示 `forbidden` ✅
+
+**症状**：预览 HTML 文件时 iframe 里只有一行裸文本 `forbidden`；而「临时解锁」后又能看。
+
+**根因（三层）**：
+
+1. DSH Desktop 在**扩展模式**下给所有路由套了一层请求围栏：`ordinaryBrowserEnabled` 恒为 false，
+   不带 Electron 注入的 `x-dsh-desktop-renderer` 头的请求一律 `403 + "forbidden"`；
+2. 该头只注入给 **mainFrame** 与**同源**子框架；
+3. 预览 iframe 的 sandbox 令牌不含 `allow-same-origin`，请求时其源为 `null` → 拿不到头 → 403。
+
+与「是否升级了插件基线」无关（v0.18.0 起行为一致）。
+
+**处置**：插件已在 1.2.0+ 用 **`srcDoc` 交付**修复（主框架取文档 → 注入 `<base>` → 注入 iframe），
+`main` 上对应提交 `4c242ac`。**不要**通过给 iframe 加 `allow-same-origin` 来"修"——那是安全降级。
+
+**验证**：
+- 沙箱态下自包含 HTML（含内联脚本）能正常渲染；
+- 有外链资源的 HTML 在沙箱态下缺资源属**已知限制**，点「临时解锁」后应完整显示。
+
+**排查命令**（确认宿主围栏在起作用）：
+
+```bash
+lsof -nP -iTCP -sTCP:LISTEN | grep -i dsh          # 找宿主端口（每次启动可能不同）
+curl -s -o /dev/null -w '%{http_code}\n' "http://127.0.0.1:<端口>/"   # 无渲染器头 → 403
+```
+
+## §4 插件面板盖住宿主/第三方弹窗 ✅
+
+**症状**：打开「社区插件市场」（宿主自带 `dsh-community-market`）时，弹窗左下角被本插件的
+文件面板整齐切掉一块。
+
+**根因**：桌面壳的有框模式会给上游 `#root` 打标 `data-dsh-desktop-content-viewport` 并施加
+`isolation: isolate`，使 `#root` 成为**层叠上下文**；宿主的 overlay 层（`.dshDesktopOverlay`，
+`z-index: 1000`）位于其中。插件面板宿主若挂在 `document.body`（该上下文之外）且是定位元素，
+就会画在整个上下文之上，把 overlay 里的弹窗盖住。
+
+**处置**：已修（`4422001`）——面板宿主改为挂进 `#root[data-dsh-desktop-content-viewport]`，
+无标记时回退 `document.body`。**不要**通过调大 `z-index` 解决（25 的取义见
+[02-系统架构](02-系统架构) §四；乱调会破坏与宿主其他层级的关系）。
+
+**验证**：插件市场弹窗完整盖住本插件面板，同时本插件面板仍在对话内容之上。
+
+## §5 终端不可用 / `node-pty` 加载失败（仅 v0.19.1 线）✅
+
+**症状**：终端面板报 shell 启动失败或提示 `node-pty` 加载失败；`pnpm install` 阶段报
+"ignored build scripts"。
+
+**根因**：pnpm 11 默认**拦截依赖的构建脚本**，`node-pty` 的原生二进制没被编译。
+（`main` 依赖 `node-pty`；`sync/v0.24.1` 已移除该依赖，终端由宿主内置承担。）
+
+**处置**：
+
+```bash
+cd ~/.dsh/profiles/<profile>
+pnpm approve-builds            # 选中 node-pty
+pnpm rebuild node-pty          # 必要时
+# ⌘Q 完整退出 DSH 再启动
+```
+
+**验证**：终端能开出 shell；`node_modules/node-pty/build/Release/*.node` 存在。
+
+## §6 改了代码，界面没变 ✅
+
+**症状**：源码已改、`pnpm build` 也跑了，但界面行为仍是旧的。
+
+**根因（三个叠加因素）**：
+
+1. 产物**非字节确定性**，且 profile 的 `file:` 依赖是**复制**语义 → profile 里仍是旧副本；
+2. `lib/client.js` 是浏览器的 `window.__ModuleLoader__.load({...})` bundle，**不是 CJS/ESM**，
+   在 Node 里 `require` 会因 `window is not defined` 报错——因此不能用「在 Node 里试跑」来验证前端改动；
+3. host 半的改动必须重启进程（client 半有热加载，host 半没有）。
+
+**处置**：
+
+```bash
+cd <插件仓库> && pnpm build
+cd ~/.dsh/profiles/<profile> && pnpm install      # 刷新 file: 副本
+# ⌘Q 完整退出 DSH → 重启
+```
+
+**验证**：比对两边产物 sha：
+
+```bash
+shasum -a 256 <插件仓库>/lib/client.js \
+  ~/.dsh/profiles/<profile>/node_modules/dsh-apes-sidebar/lib/client.js
+```
+
+## §7 DSH 拒绝加载插件 / entry pending
+
+**症状**：插件目录存在，但宿主不加载，或 loader 报 entry pending / 恢复模式。
+
+**根因**：插件的声明面不合法或不被接受，常见于：
+- `dsh.plugin.json` 的 `engines.dsh` 与宿主不符；
+- bundle patch / 挂载行的 `insert` 结构不合法（例如把声明写成宿主无法解析的形态）；
+- 同 id 重复挂载（`duplicate loader entry id` / `duplicate prefix route`）。
+
+**处置**：
+
+```bash
+cat <插件仓库>/dsh.plugin.json                      # 检查 id / engines / main
+cat <插件仓库>/cordis.patch.yml                     # 检查 insert 结构与守卫表达式
+grep -n "cordis.patch\|dsh-apes-sidebar" ~/.dsh/profiles/<profile>/package.json
+```
+
+确保只有一条挂载通道、`name` 与实际包名一致（本 fork 为 `dsh-apes-sidebar`），
+`engines.dsh` 与宿主版本相容。改完 `pnpm install` + **完整重启**。
+
+**验证**：启动日志无 loader 报错；右列出现插件 tab。
+
+## §8 DSH 启动进「恢复模式」
+
+**症状**：DSH 启动后进入恢复/安全模式，插件与侧边栏都不正常。
+
+**根因**：profile 或应用配置被写成**错误类型**。典型是材质/透明度字段要求**字符串**
+（`"off"` / `"transparent"`），但被 YAML 序列化成了布尔 `false` —— 宿主按类型校验失败即进恢复模式。
+
+**处置与验证**：
+
+```bash
+python3 -c "import yaml;d=yaml.safe_load(open('$HOME/.dsh/settings.yaml'));v=d.get('macosMaterial');print(repr(v), type(v).__name__)"
+# 期望：'off' str（或 'transparent' str）；若为 False bool → 改回字符串
+```
+
+改配置前**先备份**，改完**回读校验类型**（见 [05-运维手册](05-运维手册) §五）。
+
+---
+
+## 附：定位手法（本次会话验证有效）
+
+1. **先按用户可见文案 grep 找归属**：`grep -rl "<界面上的中文短语>" <app>/lib <profile>/node_modules`。
+   若两边都搜不到，说明它来自**运行时下载/缓存**（例如市场插件），再按 `NSUserData` 缓存或
+   `desktop-market/state.json` 之类线索去找提供方。
+2. **再读提供方自己的 CSS/DOM 结构**：拿到它声明的 z-index、定位方式与所在槽位
+   （如 `renderSlot("shell.overlay")`），据此判断是「它太高」还是「我们太高」。
+3. **层叠问题先找 `isolation` / `transform` / `filter` / `contain`**：这些才是层叠上下文与包含块的真正来源，
+   比 z-index 数值更关键。
+4. **像素证据要用原图量**：交给视觉模型的截图会被缩放（1920→1280），裁剪坐标 ≠ 屏幕坐标；
+   用 PIL 在原图上量边界、比对 RGB 剖面，再下结论。

docs/wiki/07-开发与测试.md

@@ -0,0 +1,164 @@
+# 07 · 开发与测试
+
+> 面向改代码的人（与 agent）。**先读 [02-系统架构](02-系统架构) §六「关键不变量」**，
+> 再动手改，能省掉大部分回退。
+
+## 一、工程约定
+
+| 项 | 约定 |
+| --- | --- |
+| 语言 | TypeScript **strict**（含 `noUncheckedIndexedAccess`）、ESM、导入写 `.ts` 扩展名 |
+| 构建 | `tsdown`（rolldown），host/client 双产物；懒加载 chunk 走 `src/client/chunks/` |
+| 包管理 | `pnpm`（11.x）；`pnpm install` 会触发 `prepare` 构建 |
+| 测试 | `vitest`；默认 node 环境，需要 DOM 的 spec 用 `// @vitest-environment jsdom` |
+| 宿主 peer | `dsh-better-sidebar`（本仓库已改名）**永不打包**，必须留在 peer/neverBundle 一侧 |
+| 命名 | 信息层 tab id 前缀 `apes:`；插件名 `dsh-apes-sidebar` |
+| 颜色 | 只用 `--dsw-alias-*` 设计令牌（`var(--token, <回退>)`），不写死色值 |
+
+## 二、目录结构（`main` 实况）
+
+```
+src/
+  index.ts              HOST 入口：name / inject / apply(ctx, config)，路由与围栏装配
+  invariant.ts          零依赖不变量面（host/client 共用）
+  context-types.ts      cordis 服务面契约（ctx.sessions / sidebarRight / …）
+  trust-fence.ts        请求信任围栏（Host 头 / 令牌）
+  html-route.ts         /sidebar/html 路由（路径围栏 + 体积上限）
+  config.ts             挂载行配置 schema 与默认值（readLimit / mediaLimit / …）
+  fs-*.ts git.ts …      文件系统、Git、会话、任务、终端等 host 能力
+  client/
+    index.tsx           CLIENT 入口（apply）：装配 store/service/native/apes
+    service.ts          ctx.betterSidebar 服务实现（对外 API + 能力清单）
+    state.ts            侧边栏状态存储（store）
+    native/             原生右侧栏适配（tab 记录、tab 体、tab 芯片标题）
+    builtins/           内置面板：editor / git / subagent / sidechat / terminal / browser + 预览器
+    sidebar/            自绘底部工作台与开合控件
+    apes/               信息层三 tab（本 fork 增量：tabs.tsx / icons.tsx / locales.ts）
+    changes/ diff/      文件变动与 diff 视图
+    chunks/             懒加载 chunk：editor / locale / mermaid / terminal
+    locales*.ts         i18n（`locales.ts` + 19 个语言覆盖文件）
+    *.module.css        组件样式（含 sidebar.module.css：面板宿主层契约）
+tests/                  vitest specs（131 个文件，含 e2e/ 的挂载脚本型用例）
+scripts/                install / switch / e2e 挂载 / 发布辅助
+docs/                   external-plugin-guide.md（对外契约）+ plans/（上游历史设计）+ wiki/（本百科源文件）
+```
+
+## 三、门禁（提交前必跑）
+
+```bash
+pnpm typecheck     # tsc --noEmit（strict）
+pnpm build         # rm -rf lib && tsc(d.ts) && tsdown
+pnpm test          # vitest run
+```
+
+当前基线（本次会话实测）：`main` = 131 文件 / **1367 通过** + 9 skip；
+`sync/v0.24.1` = 141 文件 / **1515 通过** + 9 skip。全量 test 约 3–4 分钟。
+**任何一条不过就不要提交**；三条全绿才算完成。
+
+## 四、测试体系（按层次）
+
+| 层次 | 环境 | 手法 | 代表 spec |
+| --- | --- | --- | --- |
+| 宿主插件形状 / 对外契约 | node | 断言导出面与语义（含与 `package.json` 的版本一致性） | `smoke.spec.ts` · `plugin-shape.spec.ts` · `service.spec.ts` · `consumer-types.ts` |
+| 原生侧边栏适配 | node | 用「类型为真、运行时为假」的 mock 注册表 | `native-surface.spec.ts` |
+| 面板宿主与层叠契约 | node + jsdom | CSS 断言 + DOM 挂载点解析 | `panel-host-css.spec.ts` · `panel-host-parent.spec.ts` |
+| 预览交付 | node + jsdom | 纯逻辑（`<base>` 注入）+ 客户端挂载（stub `fetch`，`createRoot` + `act`） | `html-preview.spec.ts` · `html-preview-frame.spec.tsx` |
+| 沙箱契约 | node | 对渲染结果做**字符串断言**（服务端渲染把 `srcDoc` 输出为 camelCase `srcDoc=""`，与客户端设置的真实属性 `srcdoc` 不同 —— 断言方式随之不同） | `sandbox-views.spec.tsx` |
+| 信息层 tab | node | mock `ctx.sessions.list` 与投影 | `apes-tabs.spec.ts` |
+| 桌面环境探测 | node | stub 全局（URL stamp / preload 标记） | `desktop-env.spec.ts` |
+
+约定：
+- **不引入 jsdom 到默认环境**：需要 DOM 的 spec 在文件头写 `// @vitest-environment jsdom`。
+- **不依赖真实 DSH 宿主**：需要真宿主的用例归到 `tests/e2e/`（脚本型挂载），不进单元门禁。
+- 新增「契约」必须**同时新增 pin 它的 spec**（例如本文档提到的 25 层级、沙箱令牌、`srcDoc` 交付方式，
+  都有对应断言）。改契约 = 改代码 + 改 spec，两者必须一起提交。
+
+## 五、扩展点（对外服务）
+
+其他插件通过 `ctx.betterSidebar` 接入：
+
+```ts
+// 注册一个 tab 类型
+await ctx.betterSidebar.registerTab(descriptor)
+// 注册一个文件预览器
+await ctx.betterSidebar.registerFileViewer(viewer)
+```
+
+- 服务按**能力清单**做前向兼容门控（能力只增不减），消费方应据此判断可用性而非版本号比较。
+- 完整契约、字段表与示例见仓库内 [docs/external-plugin-guide.md](../blob/main/docs/external-plugin-guide.md)。
+- 改服务面时：**只能新增**；删除或改语义需同步更新能力清单、指南与本百科。
+
+## 六、上游同步：测量式 re-base（本项目的方法论）
+
+**不 merge 上游**。上游每个版本差距可达数百文件，直接合并会引入无关变更并放大冲突面；
+本项目改用「先测量、再重建、后补增量」：
+
+### 步骤
+
+**① 测出自己的增量（把改名归一化掉）**
+
+```python
+# 对每个变更文件：取出两边 blob，把改名归一化后比较
+old = git('show', f'{base}:{path}'); new = git('show', f'HEAD:{path}')
+rename_only = old.replace('dsh-better-sidebar', 'dsh-apes-sidebar') == new
+```
+→ 得到三张清单：**仅改名**（自动处理）/ **真改动** / **新增**。数量级参考：v0.19.1→v0.24.1 为
+78 / 11 / 10。
+
+**② 确定改名的精确范围（不要重新推断）**
+
+```bash
+# 仍保留上游名字的文件 = 有意保留（本仓库为 README.md、package.json、docs/plans/*）
+comm -12 <(git grep -l 'dsh-better-sidebar' <旧基线> | cut -d: -f2 | sort) \
+         <(git grep -l 'dsh-better-sidebar' HEAD | cut -d: -f2 | sort)
+```
+其余文件只做子串替换 `dsh-better-sidebar` → `dsh-apes-sidebar`；**camelCase 服务名 `betterSidebar` 必须保留**。
+
+**③ 造一个"改名归一化基座"，让增量与改名解耦**
+
+```bash
+git checkout -B tmp/norm-<旧基线> <旧基线 tag>
+#   → 套同一口径改名 → commit
+git diff tmp/norm-<旧基线> HEAD -- . ':(exclude)pnpm-lock.yaml' > /tmp/apes-delta.patch
+# 校验：这条 diff 的文件清单必须恰好等于 ① 的「真改动 + 新增」
+```
+
+**④ 在新基线上重建 + 三点合并**
+
+```bash
+git checkout -B sync/<新基线 tag> <新基线 tag>
+#   → 套同一口径改名 → commit（"rename only"）
+git apply -3 /tmp/apes-delta.patch        # 冲突会以 <<<<<<< ours / >>>>>>> theirs 留存（命令本身不失败）
+```
+
+**⑤ 逐条判读冲突（只有五种形态）**
+
+| 形态 | 判定 |
+| --- | --- |
+| 版本/身份 JSON | 取**新基线**侧，再改成本 fork 的版本；两侧各自新增的元数据取**并集**（依赖、files 条目、`forkedFrom` 块） |
+| 上游搬走了某个 import | 取上游的新路径，保留本 fork 的新 import |
+| 上游新环境里的注册块 | 保留本 fork 的块，放进上游的新上下文 |
+| 同一函数两边都定义（上游上移/下移了它） | 删除本 fork 那份；用 `grep -c 'const <name>'` 断言只剩 1 处 |
+| 长文档（README） | 整体取上游原文，再机械套上本 fork 的两处增量：顶部 fork notice + 包名替换（**跳过** `github.com/<上游 org>` 与徽章域名行） |
+
+**⑥ 迁移检查（API 漂移）+ 门禁**
+
+- 先**解完所有冲突标记再** `pnpm install`（`prepare: tsdown` 会因为语法错误直接失败），
+  并**删掉 lockfile 重新生成**（不要把旧 lockfile 带过来）。
+- 逐条跑 `pnpm typecheck` 修类型漂移。经验：漂移通常集中在**本 fork 自己新增的模块**里。
+  上游会在 `context-types.ts` 的注释里写清迁移路径（例：0.1.6 的 `subagentsByParent`
+  → 0.1.7 的 `projectionsBySession[id].values.subagentCatalog`，`list.current` 被删除），照注释做即可。
+- 最后跑门禁三连，并且**用 `grep` 核对关键标记**（tab id、`srcDoc`、`dsh-desktop-content-viewport` 等）。
+
+**⑦ 收尾（纪律）**
+
+- 安全锚点：`backup/pre-sync-<新基线>` 分支 + `apes-v<版本>` tag，**推送远端**。
+- **不要把新线同步进正在使用的 profile**：peer 范围可能已跨 minor，同步过去只会「静默失效」，
+  同时把本机环境弄脏。保持 profile 在已验证的线上。
+
+## 七、提交与分支纪律
+
+- 提交信息用 `type(scope): 摘要`（`feat` / `fix` / `chore` / `docs` / `refactor`），正文说明**为什么**与验证方式。
+- 一个提交一件事；re-base 类改动拆成「rename only」+「增量移植」两个提交，便于回溯与回滚。
+- 分支命名：`sync/<上游 tag>`（跟随上游）、`backup/pre-sync-<基线>`（锚点）、其余按需。
+- 提交前：门禁三连 + 关键标记 grep + （若涉及部署）提醒 profile 重装与完整重启。

docs/wiki/Home.md

@@ -0,0 +1,82 @@
+# apes-sidebar 项目百科
+
+> DeepSeek Harness（DSH）的**服务化右侧边栏工作台** + **apes 信息层**。
+> 本项目是 [`dsh-better-sidebar`](https://github.com/omdsh-dev/DSH-better-sidebar)（MIT）的 fork，
+> 在其「文件 / 文件变动 / 任务 / 侧边对话 / 终端 / 浏览器」工作台之上，追加三个信息层标签页：
+> **智能体（agents）/ 应用（apps）/ 画像（profile）**。
+
+## 一、项目速览
+
+| 项 | 值 |
+| --- | --- |
+| 仓库 | `figmar/apes-sidebar`（公开） |
+| 默认分支 | `main` |
+| 许可证 | MIT（fork 自 `omdsh-dev/DSH-better-sidebar`） |
+| 语言 / 构建 | TypeScript（strict）· `tsdown`（rolldown）· `pnpm` |
+| 宿主 | DSH Desktop（Electron 壳）或 DSH Web profile |
+| 上游跟随方式 | 不合并上游提交，而是**测量式 re-base**（见 [07-开发与测试](07-开发与测试)） |
+
+## 二、两条版本线（重要）
+
+本仓库同时维护两条互相独立、**不能同时挂载**的版本线（两条线都注册 `ctx.betterSidebar`，
+cordis entry id 冲突，第二个会被丢弃）：
+
+| 分支 | 版本 | 上游基线 | peer / 宿主要求 | 状态 |
+| --- | --- | --- | --- | --- |
+| **`main`** | 1.2.0 | `dsh-better-sidebar` **v0.19.1**（`8753096`） | `^0.1.5-rc.1`（DSH **0.1.5-rc.1+**） | 已在本机 DSH Desktop 2.0.10（`dsh 0.1.5-rc.2`）实机运行 |
+| **`sync/v0.24.1`** | 1.3.0 | `dsh-better-sidebar` **v0.24.1**（`a2751cf`） | `^0.2.0-rc.1`（DSH **0.2.0-rc.1+**） | 构建与测试全绿，**待具备 0.2.0 宿主实机验证** |
+
+> ⚠️ **宿主的兼容性预检是「静默禁用」，不报错、不加载、无日志。**
+> 宿主用 `semver.satisfies(host, peerRange, { includePrerelease: true })` 判定；caret 范围跨 minor
+> 不成立（`^0.1.5-rc.1` 在 `0.2.0` 宿主上为 false），于是整行被跳过。
+> **现象 = 插件"好像没装"**。选线请先看宿主版本，见 [04-部署指南](04-部署指南)。
+
+## 三、文档地图
+
+| 页面 | 内容 |
+| --- | --- |
+| [01-需求分析](01-需求分析) | **官方原生 vs 装了本包**：官方右列只有「文件树 + 只读文本预览」（附官方包证据），九个 tab 是一个整体需求；7 条需求变化洞察、U1–U6、已知限制 |
+| [02-系统架构](02-系统架构) | host/client 拆分、三层接口面、面板宿主层级契约、关键不变量 |
+| [03-功能说明](03-功能说明) | 全部标签页与预览器、信息层数据来源、i18n、主题令牌、安全边界 |
+| [04-部署指南](04-部署指南) | 环境矩阵、选线、profile 接线、构建、验收清单、卸载 |
+| [05-运维手册](05-运维手册) | 版本线与分支策略、回滚剧本、发布纪律、巡检、备份铁律 |
+| [06-故障排查](06-故障排查) | 症状 → 根因 → 处置（含全部实机验证过的案例） |
+| [07-开发与测试](07-开发与测试) | 工程约定、目录、门禁、测试体系、扩展点、上游 re-base 方法 |
+
+## 四、快速开始（TL;DR）
+
+```bash
+# 1) 构建（Node ≥ 20，pnpm）
+pnpm install && pnpm typecheck && pnpm build && pnpm test
+
+# 2) 接到 DSH profile（以桌面 profile 为例，使用 file: 链接依赖）
+#    在 ~/.dsh/profiles/desktop/package.json 中：
+#      "dsh-apes-sidebar": "file:/绝对路径/dsh-apes-sidebar"
+#    并在 dsh.profile.bundles 列表里加入 "dsh-apes-sidebar"
+
+# 3) 让 profile 重新安装依赖，然后 ⌘Q 完整退出 DSH 再启动
+```
+
+完整步骤与坑见 [04-部署指南](04-部署指南)。
+
+## 五、仓库内的事实源
+
+| 位置 | 说明 |
+| --- | --- |
+| `README.md` | 面向用户的功能与安装说明（主体沿用上游文档，顶部有 fork notice） |
+| `AGENTS.md` | 面向 agent/协作者的工程约定（构建、布局、硬性规则、测试约定）⚠️ 注意：本文件当前描述的是**另一套 from-scratch 实现**，与 `main` 的 fork 树不一致，以源码为准 |
+| `docs/external-plugin-guide.md` | 插件接入指南：`ctx.betterSidebar.registerTab / registerFileViewer` 的对外契约 |
+| `docs/plans/` | 上游历史设计文档（保持上游原样，未随 fork 改名） |
+| `docs/wiki/` | **本百科的源文件**（Gitea wiki 页面的可版本化副本，由 `scripts/push-wiki.sh` 推送） |
+| `scripts/switch.sh` | 两线切换脚本（`aps` ↔ `upstream`），含 `--status` |
+
+## 六、谱系说明（如实交代）
+
+`figmar/apes-sidebar` 这个仓库先后承载过同一产品族的三代实现：
+
+1. **v1**：早期 JS bundle 版侧边栏插件（仓库描述里提到的「可配置显示名 / 预设 feyOS」即出自那一代）；
+2. **v2**：from-scratch 重写（`src/index.ts` + `src/client/index.tsx` 结构，五个 `apes:*` tab），
+   即 `AGENTS.md` 所描述的那一套，其产物不在当前 `main` 上；
+3. **当前线（v0.19.1 / v0.24.1 fork）**：即 `main` 与 `sync/v0.24.1` 上的代码——本百科描述的对象。
+
+若需要把本百科改写成描述 v2 重写版，请告知，源文件在 `docs/wiki/` 可直接替换。

dsh.plugin.json

@@ -1,10 +1,10 @@
 {
-  "id": "dsh-external/dsh-better-sidebar",
-  "version": "0.19.0-alpha.1",
+  "id": "dsh-external/dsh-apes-sidebar",
+  "version": "1.2.0",
   "main": "./lib/index.js",
   "description": "VSCode 风格右侧侧边栏：文件资源管理器 / 编辑器 / 终端 / Git / 浏览器，按会话隔离。暴露服务供其他插件注册侧边栏页面和文件预览器",
   "engines": {
-    "dsh": ">=0.1.5-alpha.2"
+    "dsh": ">=0.1.5-rc.1"
   },
   "contributes": {
     "tools": [],

package.json

@@ -1,7 +1,7 @@
 {
-  "name": "dsh-better-sidebar",
-  "version": "0.19.0-alpha.1",
-  "description": "DSH web plugin: a VSCode-like right sidebar (explorer / editor / terminal / git / browser), isolated per conversation session. Exposes a service for other plugins to register sidebar tabs and file viewers.",
+  "name": "dsh-apes-sidebar",
+  "version": "1.2.0",
+  "description": "APE fork of dsh-better-sidebar (base v0.19.1): VSCode-like right sidebar (explorer / editor / terminal / git / browser) isolated per session, plus apes:* information-layer tabs (agents / apps / profile). Forked from omdsh-dev/DSH-better-sidebar under MIT.",
   "type": "module",
   "repository": {
     "type": "git",
@@ -70,7 +70,8 @@
     "cordis.patch.yml",
     "README.md",
     "README_EN.md",
-    "LICENSE"
+    "LICENSE",
+    "scripts/switch.sh"
   ],
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('lib',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && tsdown",
@@ -80,29 +81,34 @@
     "watch": "tsdown --watch",
     "prepare": "tsdown",
     "test": "vitest run",
+    "test:windows": "vitest run --maxWorkers=1",
     "test:mount": "bash scripts/e2e-mount.sh",
     "test:mount:aggregate": "bash scripts/e2e-aggregate-mount.sh",
     "clean": "node -e \"require('node:fs').rmSync('lib',{recursive:true,force:true})\"",
     "check:consumer-types": "bash scripts/check-consumer-types.sh",
-    "lint": "eslint ."
+    "lint": "eslint .",
+    "switch": "bash scripts/switch.sh",
+    "switch:status": "bash scripts/switch.sh --status",
+    "switch:aps": "bash scripts/switch.sh aps",
+    "switch:upstream": "bash scripts/switch.sh upstream"
   },
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.5-alpha.2",
-    "@deepseek-ai/dsh-client-locale": "^0.1.5-alpha.2",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.5-alpha.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.5-alpha.2",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.5-alpha.2",
-    "@deepseek-ai/dsh-client-ui-sidebar-right": "^0.1.5-alpha.2",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-alpha.2",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.5-alpha.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.5-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.5-alpha.2",
-    "@deepseek-ai/dsh-settings": "^0.1.5-alpha.2",
-    "@deepseek-ai/dsh-subagent": "^0.1.5-alpha.2",
-    "@deepseek-ai/dsh-tools": "^0.1.5-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-agent": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-sidebar-right": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-settings": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-subagent": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.2.0-rc.2",
     "@huanlin/dsh-plugin-better-locale": "^0.1.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
@@ -149,29 +155,30 @@
   },
   "devDependencies": {
     "@cordisjs/plugin-loader": "^1.0.0-rc.5",
-    "@deepseek-ai/dsh-agent": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-agent-loop": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-attachment": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-client-locale": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-client-ui-conversation": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-client-ui-settings": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-client-ui-sidebar-right": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-client-ui-slots": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-code-runtime": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-host-webserver": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-invariants": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-llm": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-scope": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-session": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-session-persistence": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-session-projection": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-settings": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-subagent": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-tools": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-user-approval": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-util-time": "0.1.5-alpha.2",
+    "@deepseek-ai/dsh-agent": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-agent-loop": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-attachment": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-locale": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-sidebar-right": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-code-runtime": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-invariants": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-scope": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-session-persistence": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-session-projection": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-settings": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-subagent": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-user-approval": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-util-time": "0.1.5-rc.2",
+    "@eslint/js": "^10.0.1",
     "@huanlin/dsh-plugin-better-locale": "^0.1.0",
     "@playwright/test": "^1.62.1",
     "@shikijs/langs": "^4.3.1",
@@ -184,6 +191,9 @@
     "@xterm/xterm": "^5.5.0",
     "anser": "^2.3.5",
     "cordis": "^4.0.0-rc.8",
+    "eslint": "^10.9.1",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^17.12.0",
     "jsdom": "^29.1.1",
     "katex": "^0.16.47",
     "lightningcss": "^1.32.0",
@@ -199,17 +209,19 @@
     "micromark-util-sanitize-uri": "^2.0.1",
     "micromark-util-symbol": "^2.0.1",
     "micromark-util-types": "^2.0.2",
-    "shiki": "^4.3.1",
     "react": "^18.2.0",
     "react-dom": "18.2.0",
+    "shiki": "^4.3.1",
     "tsdown": "^0.22.2",
     "typescript": "^5.6.0",
+    "typescript-eslint": "^8.69.0",
     "unrun": "^0.2.39",
-    "vitest": "^4.1.8",
-    "@eslint/js": "^10.0.1",
-    "eslint": "^10.9.1",
-    "eslint-plugin-react-hooks": "^7.1.1",
-    "globals": "^17.12.0",
-    "typescript-eslint": "^8.69.0"
+    "vitest": "^4.1.8"
+  },
+  "forkedFrom": {
+    "name": "dsh-better-sidebar",
+    "version": "0.19.1",
+    "commit": "8753096",
+    "url": "https://github.com/omdsh-dev/DSH-better-sidebar"
   }
 }

scripts/check-consumer-types.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Consumer-facing type surface check: build a tiny standalone consumer that
-# imports `dsh-better-sidebar/client/service` WITHOUT @types/node and with
+# imports `dsh-apes-sidebar/client/service` WITHOUT @types/node and with
 # skipLibCheck: false, then type-check it with the repo's tsc.
 #
 # This is the exact scenario the v0.12.0 API work cares about: the shipped
@@ -35,14 +35,14 @@ mkdir -p "$WORK/node_modules"
 # (GetFinalPathNameByHandle on Windows) expands junctions, which bash-level
 # resolution may leave untouched; node is guaranteed here (tsc runs below).
 resolve_dir() { node -e 'process.stdout.write(require("node:fs").realpathSync.native(process.argv[1]))' "$1"; }
-ln -s "$(resolve_dir "$(pwd)")" "$WORK/node_modules/dsh-better-sidebar"
+ln -s "$(resolve_dir "$(pwd)")" "$WORK/node_modules/dsh-apes-sidebar"
 # The vendored cordis base (and, through its realpath, cosmokit / standard-schema)
 # must resolve so the consumer can type `Context` against the DSH runtime scope.
 mkdir -p "$WORK/node_modules/@deepseek-ai"
 ln -s "$(resolve_dir "$(pwd)/node_modules/@deepseek-ai/cordis")" "$WORK/node_modules/@deepseek-ai/cordis"
 # Loud guard: both links must resolve to a package root, or tsc below would
 # report misleading module-resolution errors.
-for pkg_json in "$WORK/node_modules/dsh-better-sidebar/package.json" "$WORK/node_modules/@deepseek-ai/cordis/package.json"; do
+for pkg_json in "$WORK/node_modules/dsh-apes-sidebar/package.json" "$WORK/node_modules/@deepseek-ai/cordis/package.json"; do
   if [ ! -f "$pkg_json" ]; then
     echo "[check-consumer-types] FAIL: $pkg_json does not resolve (broken link). Link layer:" >&2
     ls -la "$WORK/node_modules" "$WORK/node_modules/@deepseek-ai" >&2 || true
@@ -51,14 +51,14 @@ for pkg_json in "$WORK/node_modules/dsh-better-sidebar/package.json" "$WORK/node
 done
 
 cat > "$WORK/check.ts" <<'EOF'
-import { SIDEBAR_FEATURES, SIDEBAR_SERVICE_VERSION } from 'dsh-better-sidebar/client/service'
-import type {} from 'dsh-better-sidebar/client/service'
+import { SIDEBAR_FEATURES, SIDEBAR_SERVICE_VERSION } from 'dsh-apes-sidebar/client/service'
+import type {} from 'dsh-apes-sidebar/client/service'
 import type {
   BetterSidebarService, FileViewerDescriptor, OpenTabSeed, SidebarSettingsRenderProps,
   TabComponentProps, TabDescriptor,
-} from 'dsh-better-sidebar/client/service'
-import type { SessionScope, SidebarSnapshot, SidebarState, SidebarStore, SidebarTab } from 'dsh-better-sidebar/client/service'
-import type { SidebarPrefs } from 'dsh-better-sidebar/client/service'
+} from 'dsh-apes-sidebar/client/service'
+import type { SessionScope, SidebarSnapshot, SidebarState, SidebarStore, SidebarTab } from 'dsh-apes-sidebar/client/service'
+import type { SidebarPrefs } from 'dsh-apes-sidebar/client/service'
 // The vendored-cordis path: `Context` from '@deepseek-ai/cordis' plus the
 // side-effect type import above must expose `ctx.betterSidebar` — the consumer
 // never needs to import this package's own Context type.
@@ -126,14 +126,14 @@ set -e
 # Fail only on errors that mention OUR package / declarations / the fixture.
 # Upstream noise (vendored cordis / cosmokit declaration warnings under the
 # repo's pinned TS lib) lives anywhere under node_modules and is filtered.
-if grep -E "dsh-better-sidebar|lib/types|check\.ts" "$WORK/strict.log" | grep -vE "node_modules/[^ ]*(cordis|cosmokit)"; then
-  echo "[check-consumer-types] FAIL: errors in the dsh-better-sidebar declaration surface:" >&2
-  grep -E "dsh-better-sidebar|lib/types|check\.ts" "$WORK/strict.log" >&2
+if grep -E "dsh-apes-sidebar|lib/types|check\.ts" "$WORK/strict.log" | grep -vE "node_modules/[^ ]*(cordis|cosmokit)"; then
+  echo "[check-consumer-types] FAIL: errors in the dsh-apes-sidebar declaration surface:" >&2
+  grep -E "dsh-apes-sidebar|lib/types|check\.ts" "$WORK/strict.log" >&2
   exit 1
 fi
 if [ "$STATUS" -ne 0 ]; then
   echo "[check-consumer-types] pass 2 note: strict mode only reports upstream declaration noise:"
-  grep -v "dsh-better-sidebar\|lib/types\|check\.ts" "$WORK/strict.log" | head -5 || true
+  grep -v "dsh-apes-sidebar\|lib/types\|check\.ts" "$WORK/strict.log" | head -5 || true
 fi
 echo "[check-consumer-types] OK: the client/service declaration surface is node-free and self-contained."
 

scripts/e2e-aggregate-mount.sh

@@ -1,9 +1,9 @@
 #!/usr/bin/env bash
 # =============================================================================
-# dsh-better-sidebar 聚合双挂载冒烟（CI + 本地）：
+# dsh-apes-sidebar 聚合双挂载冒烟（CI + 本地）：
 #
 #   场景：一个聚合 bundle（tests/fixtures/aggregate-better-sidebar）先以独立
-#   条目 id 挂载 dsh-better-sidebar，插件自身的 bundle patch 后到 —— 旧行为
+#   条目 id 挂载 dsh-apes-sidebar，插件自身的 bundle patch 后到 —— 旧行为
 #   两个实例都注册 /sidebar/api，整个插件树启动失败（duplicate prefix
 #   route）；新行为插件行检测到已有启用中的同包名挂载后自动 disabled，由
 #   聚合行接管 sidebar。
@@ -22,7 +22,7 @@
 # 环境变量（均可省略）：
 #   DSH_CMD        dsh 命令；缺省 PATH 上的 `dsh`，回退 npx 拉官方包
 #                  （同 e2e-mount.sh）
-#   TARBALL        插件 tarball；缺省仓库根 dsh-better-sidebar-*.tgz（须已 pack）
+#   TARBALL        插件 tarball；缺省仓库根 dsh-apes-sidebar-*.tgz（须已 pack）
 #   PORT           固定端口（默认 0 = OS 分配，从日志解析 URL）
 #   DSH_HOME_BASE  scratch 根目录（默认系统临时目录）。脚本始终在其下新建
 #                  本调用拥有的独立子目录，只写入/删除该子目录；调用方提供

scripts/e2e-common.sh

@@ -57,9 +57,9 @@ e2e_resolve_dsh_cmd() {
 # 过期产物上。未找到候选时返回非零，由调用方按各自文案 die。
 e2e_resolve_tarball() {
   if [ -z "${TARBALL:-}" ]; then
-    TARBALL="$(ls -t "$ROOT"/dsh-better-sidebar-*.tgz 2>/dev/null | head -1 || true)"
+    TARBALL="$(ls -t "$ROOT"/dsh-apes-sidebar-*.tgz 2>/dev/null | head -1 || true)"
     local count
-    count="$(ls "$ROOT"/dsh-better-sidebar-*.tgz 2>/dev/null | wc -l | tr -d ' ' || true)"
+    count="$(ls "$ROOT"/dsh-apes-sidebar-*.tgz 2>/dev/null | wc -l | tr -d ' ' || true)"
     [ "$count" -le 1 ] || warn "发现 $count 个 tarball，按 mtime 选用最新：$(basename "$TARBALL")（建议清理其余）"
   fi
   [ -n "$TARBALL" ] && [ -f "$TARBALL" ]
@@ -134,7 +134,7 @@ allowBuilds:
   protobufjs: true
 
 minimumReleaseAgeExclude:
-  - dsh-better-sidebar
+  - dsh-apes-sidebar
   - '@deepseek-ai/*'
 EOF
 }

scripts/e2e-mount.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # =============================================================================
-# dsh-better-sidebar 挂载冒烟编排（CI + 本地）：
+# dsh-apes-sidebar 挂载冒烟编排（CI + 本地）：
 #
 #   1. 用官方 CLI 把 npm 打包产物（tarball）真实挂载进一个全新 scratch
 #      profile（`dsh plugin --profile web add file:<tarball>`，触发
@@ -14,7 +14,7 @@
 #
 # 环境变量（均可省略）：
 #   DSH_CMD        dsh 命令；缺省 PATH 上的 `dsh`，回退 npx 拉官方包
-#   TARBALL        插件 tarball；缺省仓库根 dsh-better-sidebar-*.tgz（须已 pack）
+#   TARBALL        插件 tarball；缺省仓库根 dsh-apes-sidebar-*.tgz（须已 pack）
 #   PORT           固定端口（默认 0 = OS 分配，从日志解析 URL）
 #   DSH_HOME_BASE  覆盖 scratch 根目录（默认系统临时目录）。脚本始终在其下
 #                  新建本调用拥有的独立子目录，只写入/删除该子目录；调用方
@@ -44,7 +44,7 @@ e2e_require_cmd pnpm "dsh plugin 转发给 pnpm"
 
 e2e_resolve_dsh_cmd
 
-e2e_resolve_tarball || die "找不到 tarball（TARBALL 或 \$ROOT/dsh-better-sidebar-*.tgz）——先运行 pnpm build && pnpm pack"
+e2e_resolve_tarball || die "找不到 tarball（TARBALL 或 \$ROOT/dsh-apes-sidebar-*.tgz）——先运行 pnpm build && pnpm pack"
 TARBALL="$(cd "$(dirname "$TARBALL")" && pwd)/$(basename "$TARBALL")"
 say "tarball: $TARBALL"
 
@@ -72,18 +72,18 @@ e2e_write_profile "$PROFILE_DIR"
 say "执行 dsh plugin --profile web add file:$TARBALL ..."
 $DSH_CMD plugin --profile web add "file:$TARBALL"
 
-# 步骤 3：校验挂载生效（dsh.profile.bundles 含 dsh-better-sidebar）
+# 步骤 3：校验挂载生效（dsh.profile.bundles 含 dsh-apes-sidebar）
 if ! node -e '
   const fs = require("fs");
   const p = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
   const bundles = p.dsh?.profile?.bundles ?? [];
-  process.exit(bundles.includes("dsh-better-sidebar") ? 0 : 1);
+  process.exit(bundles.includes("dsh-apes-sidebar") ? 0 : 1);
 ' "$PROFILE_DIR/package.json"; then
-  warn "dsh-better-sidebar 未出现在 dsh.profile.bundles 中——挂载未注册"
+  warn "dsh-apes-sidebar 未出现在 dsh.profile.bundles 中——挂载未注册"
   cat "$PROFILE_DIR/package.json"
   exit 1
 fi
-say "挂载已注册：dsh.profile.bundles 包含 dsh-better-sidebar"
+say "挂载已注册：dsh.profile.bundles 包含 dsh-apes-sidebar"
 
 # 步骤 4：启动 dsh web（--port 0 = OS 分配，避免端口冲突；keyless 可起）
 say "启动 dsh web（port=${PORT}）..."

scripts/install.ps1

@@ -1,8 +1,8 @@
 ## =============================================================================
-# dsh-better-sidebar 一键安装脚本（官方 CLI 方式，Windows PowerShell 5.1+ / pwsh）
+# dsh-apes-sidebar 一键安装脚本（官方 CLI 方式，Windows PowerShell 5.1+ / pwsh）
 #
 # 通过 DSH 官方插件命令安装 npm 包并自动挂载：
-#   dsh plugin --profile web add dsh-better-sidebar@<version>
+#   dsh plugin --profile web add dsh-apes-sidebar@<version>
 #
 # 包内声明了 dsh.bundle.patch（cordis.patch.yml）：CLI 的 bundle 协调会把它
 # 自动加进 profile 的 dsh.profile.bundles，下次启动即挂载——无需手动写
@@ -52,7 +52,7 @@ param(
   [string]$Profile = 'web'
 )
 
-$PKG = 'dsh-better-sidebar'
+$PKG = 'dsh-apes-sidebar'
 $REGISTRY = if ($env:REGISTRY) { $env:REGISTRY } else { 'https://registry.npmjs.org' }
 
 # DSH_HOME：DSH_HOME 环境变量 > %USERPROFILE% > $HOME
@@ -116,11 +116,11 @@ if (!/^\s*allowBuilds:\s*$/m.test(t)) {
     }
   }
 }
-if (!/^\s*-\s+dsh-better-sidebar\s*$/m.test(t)) {
+if (!/^\s*-\s+dsh-apes-sidebar\s*$/m.test(t)) {
   if (/^\s*minimumReleaseAgeExclude:\s*$/m.test(t)) {
-    t = t.replace(/^(\s*minimumReleaseAgeExclude:\s*)$/m, "$1\n  - dsh-better-sidebar");
+    t = t.replace(/^(\s*minimumReleaseAgeExclude:\s*)$/m, "$1\n  - dsh-apes-sidebar");
   } else {
-    t += "\nminimumReleaseAgeExclude:\n  - dsh-better-sidebar\n";
+    t += "\nminimumReleaseAgeExclude:\n  - dsh-apes-sidebar\n";
   }
 }
 if (t !== before) fs.writeFileSync(p, t);
@@ -233,7 +233,7 @@ if ($addCode -ne 0) {
 $pkgJson = Get-Content -Raw (Join-Path $PROFILE_DIR 'package.json') | ConvertFrom-Json
 $bundles = $pkgJson.dsh.profile.bundles
 if ($bundles -notcontains $PKG) {
-  Warn 'dsh-better-sidebar 未出现在 dsh.profile.bundles 中——挂载未注册。'
+  Warn 'dsh-apes-sidebar 未出现在 dsh.profile.bundles 中——挂载未注册。'
   Warn "若上面的 pnpm 输出提示 ignored build scripts，请确认 $WS_YML 的 allowBuilds 后重跑本脚本。"
   exit 1
 }

scripts/install.sh

@@ -1,9 +1,9 @@
 #!/usr/bin/env bash
 # =============================================================================
-# dsh-better-sidebar 一键安装脚本（官方 CLI 方式，macOS / Linux / Windows Git Bash）
+# dsh-apes-sidebar 一键安装脚本（官方 CLI 方式，macOS / Linux / Windows Git Bash）
 #
 # 通过 DSH 官方插件命令安装 npm 包并自动挂载：
-#   dsh plugin --profile web add dsh-better-sidebar@<version>
+#   dsh plugin --profile web add dsh-apes-sidebar@<version>
 #
 # 包内声明了 dsh.bundle.patch（cordis.patch.yml）：CLI 的 bundle 协调会把它
 # 自动加进 profile 的 dsh.profile.bundles，下次启动即挂载——无需手动写
@@ -38,8 +38,8 @@
 #   minimumReleaseAgeExclude（幂等），放行本插件，避免"重跑一次才成功"。
 # - 老版本（<0.10.2）用手动挂载行，bundle 通道激活后需移除，否则双挂载
 #   （Node 半挂两次、页面两个侧边栏）。脚本会幂等移除 better-sidebar 挂载行。
-# - 回滚：dsh plugin --profile web remove dsh-better-sidebar，或把 profile 依赖
-#   改回 "dsh-better-sidebar": "link:<路径>" 再 pnpm install。
+# - 回滚：dsh plugin --profile web remove dsh-apes-sidebar，或把 profile 依赖
+#   改回 "dsh-apes-sidebar": "link:<路径>" 再 pnpm install。
 # =============================================================================
 set -euo pipefail
 
@@ -47,7 +47,7 @@ set -euo pipefail
 for arg in "$@"; do
   if [ "$arg" = "-h" ] || [ "$arg" = "--help" ]; then
     cat <<'EOF'
-dsh-better-sidebar 一键安装 / 依赖修复脚本
+dsh-apes-sidebar 一键安装 / 依赖修复脚本
 
 用法：
   bash scripts/install.sh [版本] [--restart] [--dry-run] [--profile <名>]
@@ -67,7 +67,7 @@ done
 
 DSH_HOME="${DSH_HOME:-${HOME:-${USERPROFILE:-}}/.dsh}"
 REGISTRY="${REGISTRY:-https://registry.npmjs.org}"
-PKG="dsh-better-sidebar"
+PKG="dsh-apes-sidebar"
 DSH_CMD="${DSH_CMD:-dsh}"
 
 RESTART=false
@@ -118,11 +118,11 @@ if (!/^\s*allowBuilds:\s*$/m.test(t)) {
   }
 }
 // minimumReleaseAgeExclude：放行本插件（版本无关），避免 <24h 新版本被拒
-if (!/^\s*-\s+dsh-better-sidebar\s*$/m.test(t)) {
+if (!/^\s*-\s+dsh-apes-sidebar\s*$/m.test(t)) {
   if (/^\s*minimumReleaseAgeExclude:\s*$/m.test(t)) {
-    t = t.replace(/^(\s*minimumReleaseAgeExclude:\s*)$/m, "$1\n  - dsh-better-sidebar");
+    t = t.replace(/^(\s*minimumReleaseAgeExclude:\s*)$/m, "$1\n  - dsh-apes-sidebar");
   } else {
-    t += "\nminimumReleaseAgeExclude:\n  - dsh-better-sidebar\n";
+    t += "\nminimumReleaseAgeExclude:\n  - dsh-apes-sidebar\n";
   }
 }
 if (t !== before) fs.writeFileSync(p, t);
@@ -224,7 +224,7 @@ if ! node -e '
   const bundles = p.dsh?.profile?.bundles ?? [];
   process.exit(bundles.includes(process.argv[2]) ? 0 : 1);
 ' "$PROFILE_DIR/package.json" "$PKG"; then
-  warn "dsh-better-sidebar 未出现在 dsh.profile.bundles 中——挂载未注册。"
+  warn "dsh-apes-sidebar 未出现在 dsh.profile.bundles 中——挂载未注册。"
   warn "若上面的 pnpm 输出提示 ignored build scripts，请确认 $WS_YML 的 allowBuilds 后重跑本脚本。"
   exit 1
 fi

scripts/package-registry.mjs

@@ -6,7 +6,7 @@
  *   pnpm build
  *   node scripts/package-registry.mjs
  *   dsh registry install ./registry
- *   dsh registry enable dsh-external/dsh-better-sidebar
+ *   dsh registry enable dsh-external/dsh-apes-sidebar
  *
  * The registry install copies the whole source directory (`cp -r`), so
  * installing the repo root would drag in `node_modules/` (machine-local
@@ -54,4 +54,4 @@ for (const file of files) {
   cpSync(source, target)
 }
 console.log(`registry/ assembled (${files.length} files)`)
-console.log('next: dsh registry install ./registry && dsh registry enable dsh-external/dsh-better-sidebar')
+console.log('next: dsh registry install ./registry && dsh registry enable dsh-external/dsh-apes-sidebar')

scripts/push-wiki.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# =============================================================================
+# push-wiki.sh — 把 docs/wiki/*.md 推送/更新到本仓库的 Gitea wiki
+#
+# 为什么需要它：本项目的百科源文件**版本化在仓库里**（docs/wiki/），
+# Gitea wiki 只是它的发布面。改文档 = 改仓库文件 + 跑本脚本，日志与回溯都在 git 里。
+#
+# 行为：
+#   · 幂等：页面不存在则 POST 新建，已存在则 PATCH 覆盖（标题 = 文件名去掉 .md）
+#   · 凭据来自 `git credential fill`（与推代码同一套），脚本自身不存任何 token
+#   · 凭据经临时 netrc 文件传给 curl（600 权限，退出即删），不进入 argv
+#
+# 用法：
+#   bash scripts/push-wiki.sh                 # 推送全部页面
+#   bash scripts/push-wiki.sh 05-运维手册      # 只推指定页面（按文件名/片段匹配）
+#   WIKI_REMOTE=origin bash scripts/push-wiki.sh   # 指定 remote（默认 gitea，缺失则 origin）
+# =============================================================================
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+WIKI_DIR="$ROOT/docs/wiki"
+FILTER="${1:-}"
+
+# ---- 解析 remote / owner / repo -------------------------------------------
+pick_remote() {
+  for r in "${WIKI_REMOTE:-}" gitea origin; do
+    [ -z "$r" ] && continue
+    if git remote get-url "$r" >/dev/null 2>&1; then echo "$r"; return 0; fi
+  done
+  echo "无法找到可用的 git remote（试过: ${WIKI_REMOTE:-<空>} gitea origin）" >&2
+  return 1
+}
+REMOTE="$(pick_remote)"
+URL="$(git remote get-url "$REMOTE")"
+case "$URL" in
+  https://*) ;;
+  *) echo "本脚本只支持 https remote（当前: $URL）" >&2; exit 1 ;;
+esac
+HOST="$(printf '%s' "$URL" | sed -E 's#^https://([^/]+)/.*#\1#')"
+SLUG="$(printf '%s' "$URL" | sed -E 's#^https://[^/]+/##; s#\.git$##')"
+OWNER="${SLUG%%/*}"
+REPO="${SLUG#*/}"
+API="https://$HOST/api/v1/repos/$OWNER/$REPO/wiki"
+
+echo "wiki 目标 : $OWNER/$REPO @ $HOST (remote: $REMOTE)"
+echo "源目录    : docs/wiki"
+echo
+
+# ---- 凭据 -----------------------------------------------------------------
+CRED="$(printf 'protocol=https\nhost=%s\n\n' "$HOST" | git credential fill 2>/dev/null || true)"
+USER="$(printf '%s\n' "$CRED" | sed -n 's/^username=//p')"
+PASS="$(printf '%s\n' "$CRED" | sed -n 's/^password=//p')"
+if [ -z "$PASS" ]; then
+  echo "未从 git credential helper 取到 $HOST 的凭据（先确保 git push 能成功）" >&2
+  exit 1
+fi
+NETRC="$(mktemp)"
+chmod 600 "$NETRC"
+trap 'rm -f "$NETRC"' EXIT
+printf 'machine %s\nlogin %s\npassword %s\n' "$HOST" "$USER" "$PASS" > "$NETRC"
+
+json_body() { # $1 = file
+  python3 - "$1" <<'PY'
+import base64, json, sys, pathlib
+p = pathlib.Path(sys.argv[1])
+print(json.dumps({
+    "title": p.stem,
+    "content_base64": base64.b64encode(p.read_text(encoding="utf-8").encode("utf-8")).decode("ascii"),
+}, ensure_ascii=False))
+PY
+}
+
+api() { # $1 = method, $2 = path, $3 = body(optional) -> 输出 HTTP 码
+  local method="$1" path="$2" body="${3:-}"
+  if [ -n "$body" ]; then
+    curl -s --netrc-file "$NETRC" -o /tmp/push-wiki-resp.json -w '%{http_code}' \
+      -X "$method" -H 'Content-Type: application/json' --data-binary "$body" "$API$path"
+  else
+    curl -s --netrc-file "$NETRC" -o /tmp/push-wiki-resp.json -w '%{http_code}' -X "$method" "$API$path"
+  fi
+}
+
+# ---- 逐页推送 -------------------------------------------------------------
+shopt -s nullglob
+files=("$WIKI_DIR"/*.md)
+[ ${#files[@]} -gt 0 ] || { echo "docs/wiki 下没有 .md 文件" >&2; exit 1; }
+
+ok=0; fail=0
+for f in "${files[@]}"; do
+  title="$(basename "$f" .md)"
+  if [ -n "$FILTER" ] && [[ "$title" != *"$FILTER"* ]]; then continue; fi
+  body="$(json_body "$f")"
+
+  code="$(api POST /new "$body")"
+  if [ "$code" = "201" ]; then
+    echo "  + $title  (新建)"; ok=$((ok+1)); continue
+  fi
+  enc="$(python3 -c 'import sys,urllib.parse;print(urllib.parse.quote(sys.argv[1], safe=""))' "$title")"
+  code="$(api PATCH "/page/$enc" "$body")"
+  if [ "$code" = "200" ]; then
+    echo "  ~ $title  (更新)"; ok=$((ok+1))
+  else
+    echo "  ! $title 失败（HTTP $code）: $(head -c 200 /tmp/push-wiki-resp.json 2>/dev/null)" >&2
+    fail=$((fail+1))
+  fi
+done
+
+echo
+echo "完成：成功 $ok 页，失败 $fail 页"
+[ "$fail" -eq 0 ] || exit 1
+echo "查看： https://$HOST/$OWNER/$REPO/wiki"

scripts/switch.sh

@@ -0,0 +1,294 @@
+#!/usr/bin/env bash
+# =============================================================================
+# dsh-apes-sidebar 两线切换脚本（apes fork 线 ↔ upstream better-sidebar 线）
+#
+# 同一个 DSH profile 内**二选一**切换侧边栏插件——双装不可行（两条线都注册
+# 进 `ctx.betterSidebar`，cordis entry id 冲突，第二个被丢弃）。切换 =
+# 换 profile 依赖 + 换 dsh.profile.bundles + pnpm install + 提示重启。
+#
+#   aps       本 fork 线（dsh-apes-sidebar，含 4 个 apes:* 信息层 tab）
+#             依赖：dsh-apes-sidebar: <file: 本地路径>（本地开发）或
+#                   dsh-apes-sidebar@<版本>（npm，发布后）
+#   upstream  upstream 线（dsh-better-sidebar，官方 8 tab + 生态）
+#             依赖：dsh-better-sidebar@<版本>（registry，默认 latest）
+#
+# 用法：
+#   bash scripts/switch.sh aps        # 切到本 fork 线（本地 file: 安装）
+#   bash scripts/switch.sh upstream   # 切到 upstream 线（registry 安装）
+#   bash scripts/switch.sh upstream 0.18.0   # 指定 upstream 版本
+#   bash scripts/switch.sh --status   # 只看当前线，不改任何东西
+#
+#   通用 flag（两线均适用）：
+#   --profile <名>   目标 profile（缺省 desktop）
+#   --dry-run        只打印将执行的操作，不写任何文件
+#   -h/--help        打印本帮助
+#
+# 环境（均可省略，脚本自动探测）：
+#   DSH_HOME      默认 ~/.dsh
+#   REGISTRY      默认 https://registry.npmjs.org
+#   DSH_CMD       默认 PATH 上的 dsh，缺省 npx -y --package @deepseek-ai/dsh
+#   APS_SRC       aps 线本地源码路径（缺省 = 本仓库根，即 file: 指向自己）
+#
+# 机制（幂等，可重复跑）：
+#   1. 探测当前线（依赖里哪个包在）
+#   2. 与目标线相同 → 提示后直接退出（不重装）
+#   3. 移除另一线的依赖 + 从 bundles 摘除另一线的 bundle
+#   4. 写入目标线依赖 + 确保 workspace 放行 node-pty/protobufjs 构建
+#   5. cd profile && pnpm install（reconcileProfilePnpmWorkspace 会重建
+#      node_modules——这是预期行为，两线不共存）
+#   6. 确保 bundles 含目标线包名（bundle 通道挂载生效的判据）
+#   7. 幂等移除 cordis.patch.yml 里对手线的手动挂载行（避免双挂载）
+#   8. 提示重启 DSH
+#
+# 回滚：跑 `bash scripts/switch.sh <另一线>` 即可切回去。
+# =============================================================================
+set -euo pipefail
+
+for arg in "$@"; do
+  if [ "$arg" = "-h" ] || [ "$arg" = "--help" ]; then
+    cat <<'EOF'
+dsh-apes-sidebar 两线切换（同一 profile 内二选一）
+
+用法：
+  bash scripts/switch.sh <aps|upstream> [版本]
+  bash scripts/switch.sh --status
+
+  aps         切到本 fork 线（dsh-apes-sidebar，4 个 apes:* tab）
+  upstream    切到 upstream 线（dsh-better-sidebar，官方）
+  <版本>      仅对 upstream 生效（缺省 latest）
+  --status    只看当前线，不改动
+  --profile   目标 profile（缺省 desktop）
+  --dry-run   只打印操作，不写文件
+  -h/--help   本帮助
+
+环境变量：DSH_HOME、REGISTRY、DSH_CMD、APS_SRC（aps 本地源码路径）
+EOF
+    exit 0
+  fi
+done
+
+DSH_HOME="${DSH_HOME:-${HOME:-${USERPROFILE:-}}/.dsh}"
+REGISTRY="${REGISTRY:-https://registry.npmjs.org}"
+DSH_CMD="${DSH_CMD:-dsh}"
+# aps 线本地源码：缺省 = 本仓库根（脚本在 scripts/ 下，根 = 上一级）
+APS_SRC="${APS_SRC:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+
+APS_PKG="dsh-apes-sidebar"
+UP_PKG="dsh-better-sidebar"
+
+DRY_RUN=false
+STATUS_ONLY=false
+TARGET=""
+UP_VERSION=""
+PROFILE_NAME="desktop"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --status) STATUS_ONLY=true ;;
+    --dry-run) DRY_RUN=true ;;
+    --profile)
+      if [ $# -lt 2 ]; then echo "--profile 需要一个 profile 名（如 desktop）" >&2; exit 2; fi
+      PROFILE_NAME="$2"; shift ;;
+    aps|upstream) TARGET="$1" ;;
+    -h|--help) : ;;
+    -*) echo "未知参数: ${1}（用 -h 查看用法）" >&2; exit 2 ;;
+    *) UP_VERSION="$1" ;;  # 版本参数（仅 upstream 用）
+  esac
+  shift
+done
+
+PROFILE_DIR="$DSH_HOME/profiles/$PROFILE_NAME"
+PKG_JSON="$PROFILE_DIR/package.json"
+WS_YML="$PROFILE_DIR/pnpm-workspace.yaml"
+PATCH_YML="$PROFILE_DIR/cordis.patch.yml"
+
+say()  { printf '\033[32m[switch]\033[0m %s\n' "$*"; }
+warn() { printf '\033[33m[warn]\033[0m %s\n' "$*" >&2; }
+die()  { printf '\033[31m[error]\033[0m %s\n' "$*" >&2; exit 1; }
+
+command -v node >/dev/null 2>&1 || die "未找到 node（DSH 运行需要 Node.js ≥ 20）。"
+[ -d "$PROFILE_DIR" ] || die "找不到 profile 目录：${PROFILE_DIR}（请先初始化 ${PROFILE_NAME} profile）"
+[ -f "$PKG_JSON" ]    || die "找不到 ${PKG_JSON}（profile 未初始化）"
+
+# ── 探测当前线（依赖里哪个包在）─────────────────────────────────────────
+current_line() {
+  node -e '
+    const p = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
+    const deps = p.dependencies || {};
+    if (deps["dsh-apes-sidebar"])     console.log("aps");
+    else if (deps["dsh-better-sidebar"]) console.log("upstream");
+    else console.log("none");
+  ' "$PKG_JSON"
+}
+
+if [ "$STATUS_ONLY" = true ]; then
+  CUR="$(current_line)"
+  say "profile: ${PROFILE_NAME} (${PROFILE_DIR})"
+  case "$CUR" in
+    aps)      say "当前线：aps（${APS_PKG}）" ;;
+    upstream) say "当前线：upstream（${UP_PKG}）" ;;
+    none)     say "当前线：无（两条线都未装）" ;;
+  esac
+  # 附带显示 bundles 里的 sidebar 条目
+  node -e '
+    const p = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
+    const b = (p.dsh && p.dsh.profile && p.dsh.profile.bundles) || [];
+    const side = b.filter(x => /sidebar/.test(x));
+    console.log("bundles 里的 sidebar 条目: " + (side.length ? side.join(", ") : "（无）"));
+  ' "$PKG_JSON"
+  exit 0
+fi
+
+[ -n "$TARGET" ] || die "缺少目标线（aps | upstream）。用 --status 查看当前线。"
+
+CUR="$(current_line)"
+case "$TARGET" in
+  aps)      T_PKG="$APS_PKG";  T_DEP="file:${APS_SRC}" ;;
+  upstream)
+    T_PKG="$UP_PKG"
+    # pnpm 从依赖 key 取包名，值只给版本 spec（不含包名，否则双 @）
+    case "${UP_VERSION:-latest}" in
+      latest) T_DEP="latest" ;;
+      *)      T_DEP="$UP_VERSION" ;;
+    esac
+    ;;
+esac
+
+[ "$CUR" = "$TARGET" ] && {
+  say "当前已是 ${TARGET} 线（${T_PKG}），无需切换。"
+  say "如需强制重装：先跑 --status 确认，再手动移除依赖后重跑。"
+  exit 0
+}
+
+OTHER_PKG=""
+case "$TARGET" in
+  aps)      OTHER_PKG="$UP_PKG" ;;
+  upstream) OTHER_PKG="$APS_PKG" ;;
+esac
+
+say "切换：${CUR} → ${TARGET}（profile: ${PROFILE_NAME}）"
+say "目标依赖：${T_DEP}"
+
+if [ "$DRY_RUN" = true ]; then
+  say "[dry-run] 步骤 1：移除 ${OTHER_PKG:-（无）} 依赖 + 从 bundles 摘除 ${OTHER_PKG:-（无）}"
+  say "[dry-run] 步骤 2：写入 ${T_PKG} 依赖（${T_DEP}）"
+  say "[dry-run] 步骤 3：确保 ${WS_YML} 放行 node-pty/protobufjs 构建"
+  say "[dry-run] 步骤 4：cd ${PROFILE_DIR} && pnpm install（重建 node_modules）"
+  say "[dry-run] 步骤 5：确保 bundles 含 ${T_PKG}"
+  say "[dry-run] 步骤 6：幂等移除 ${PATCH_YML} 里 ${OTHER_PKG:-对手线} 的手动挂载行"
+  say "[dry-run] 步骤 7：提示重启 DSH"
+  exit 0
+fi
+
+# ── 步骤 1+2+5 合并：一次 node 调用完成依赖 + bundles 的对称改写 ─────────
+# 移除对手线依赖 + bundle，写入目标线依赖 + 确保目标 bundle 在列。幂等。
+node -e '
+  const fs = require("fs");
+  const p = process.argv[1];
+  const keep = process.argv[2];      // 目标包名
+  const depSpec = process.argv[3];   // 目标依赖 spec（file:... 或 pkg@ver）
+  const remove = process.argv[4];    // 对手包名（可能为空串）
+  const t = JSON.parse(fs.readFileSync(p, "utf8"));
+  t.dependencies = t.dependencies || {};
+  // 移除对手线依赖
+  if (remove) { const had = t.dependencies[remove]; delete t.dependencies[remove]; if (had) console.log("removed dep: " + remove + "=" + had); }
+  // 写入目标线依赖
+  t.dependencies[keep] = depSpec;
+  // bundles：摘除对手线，确保目标线在列
+  const prof = (t.dsh && t.dsh.profile) || {};
+  const b = prof.bundles || [];
+  const nb = b.filter(x => x !== remove);
+  if (!nb.includes(keep)) nb.push(keep);
+  t.dsh = t.dsh || {}; t.dsh.profile = prof; prof.bundles = nb;
+  fs.writeFileSync(p, JSON.stringify(t, null, 2) + "\n");
+  console.log("deps now: " + JSON.stringify(t.dependencies));
+  console.log("bundles now: " + nb.join(", "));
+' "$PKG_JSON" "$T_PKG" "$T_DEP" "$OTHER_PKG"
+say "依赖 + bundles 已改写"
+
+# ── 步骤 3：确保 workspace 放行 node-pty/protobufjs 构建（幂等）─────────
+if [ -f "$WS_YML" ]; then
+  WS_RESULT="$(node -e '
+    const fs = require("fs");
+    const p = process.argv[1];
+    let t = fs.readFileSync(p, "utf8");
+    const before = t;
+    t = t.replace(/^(\s*)(node-pty|protobufjs):.*$/gm, "$1$2: true");
+    if (!/^\s*allowBuilds:\s*$/m.test(t)) {
+      t += "\nallowBuilds:\n  node-pty: true\n  protobufjs: true\n";
+    } else {
+      for (const k of ["node-pty", "protobufjs"]) {
+        if (!new RegExp("^\\s*" + k + ":\\s*true\\s*$", "m").test(t)) {
+          t = t.replace(/^(\s*allowBuilds:\s*)$/m, "$1\n  " + k + ": true");
+        }
+      }
+    }
+    if (t !== before) fs.writeFileSync(p, t);
+    console.log(t === before ? "unchanged" : "updated");
+  ' "$WS_YML")"
+  [ "$WS_RESULT" = "updated" ] && say "已确保 ${WS_YML}：allowBuilds（node-pty/protobufjs: true）" \
+    || say "workspace 设置已就绪，跳过"
+else
+  warn "找不到 ${WS_YML}，跳过 workspace 预写（若 pnpm install 报 ignored build scripts 需手动补）"
+fi
+
+# ── 步骤 4：pnpm install（重建 node_modules——两线不共存，这是预期）──────
+command -v pnpm >/dev/null 2>&1 || die "未找到 pnpm。请安装 pnpm 9+ 并加入 PATH。"
+say "执行 cd ${PROFILE_DIR} && pnpm install（reconcileProfilePnpmWorkspace 会重建 node_modules）..."
+if ! (cd "$PROFILE_DIR" && pnpm install); then
+  die "pnpm install 失败。请确认网络可用、依赖 spec 正确，然后重试。"
+fi
+
+# ── 步骤 5 校验：bundles 含目标包（挂载生效判据）────────────────────────
+if ! node -e '
+  const p = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
+  const b = (p.dsh && p.dsh.profile && p.dsh.profile.bundles) || [];
+  process.exit(b.includes(process.argv[2]) ? 0 : 1);
+' "$PKG_JSON" "$T_PKG"; then
+  warn "${T_PKG} 未出现在 dsh.profile.bundles——挂载未注册，请检查 ${PKG_JSON}。"
+  exit 1
+fi
+say "bundle 已注册：dsh.profile.bundles 含 ${T_PKG}（下次启动自动挂载）"
+
+# ── 步骤 6：幂等移除对手线在 cordis.patch.yml 里的手动挂载行 ─────────────
+if [ -f "$PATCH_YML" ]; then
+  MOUNT_RESULT="$(node -e '
+    const fs = require("fs");
+    const p = process.argv[1];
+    const removePkg = process.argv[2];
+    if (!removePkg) { console.log("none"); process.exit(0); }
+    const lines = fs.readFileSync(p, "utf8").split("\n");
+    const out = [];
+    let i = 0;
+    let removed = false;
+    while (i < lines.length) {
+      const line = lines[i];
+      if (/^[ \t]*- insert:\s*$/.test(line)) {
+        const block = [line];
+        let j = i + 1;
+        while (j < lines.length && lines[j].trim() !== "" && !/^- \s/.test(lines[j])) {
+          block.push(lines[j]);
+          j++;
+        }
+        if (block.some((l) => new RegExp("id:\\s*" + removePkg.replace(/[-/]/g, "\\$&") + "\\b").test(l))) {
+          while (out.length && /^[ \t]*#/.test(out[out.length - 1])) out.pop();
+          i = j;
+          removed = true;
+          continue;
+        }
+      }
+      out.push(line);
+      i++;
+    }
+    if (!removed) console.log("none");
+    else { const t = out.join("\n").replace(/\n{3,}/g, "\n\n"); fs.writeFileSync(p, t); console.log("removed"); }
+  ' "$PATCH_YML" "$OTHER_PKG")"
+  [ "$MOUNT_RESULT" = "removed" ] && say "已从 ${PATCH_YML} 移除 ${OTHER_PKG} 的手动挂载行" \
+    || say "无 ${OTHER_PKG} 手动挂载行，跳过"
+else
+  say "无 ${PATCH_YML}，跳过手动挂载行清理"
+fi
+
+# ── 步骤 7：提示重启 ────────────────────────────────────────────────────
+say "切换完成：${CUR} → ${TARGET}（${T_PKG}）"
+say "下一步：重启 DSH 并硬刷新（Cmd/Ctrl+Shift+R）使新副本生效。"

src/agent-pty.ts

@@ -134,6 +134,13 @@ export interface AgentTerminalSnapshot {
   exitCode?: number | null
   /** Exit signal name if the process was killed by a signal; null otherwise. */
   exitSignal?: string | null
+
+  /**
+   * The model's active `terminal_wait_for` on this terminal (the sidebar
+   * renders the wait banner from it). Present only while a wait is
+   * registered; carries the LATEST wait when several overlap.
+   */
+  waiting?: { needle: string; since: number }
 }
 
 /** Map a POSIX signal number to its conventional name (best-effort). */
@@ -223,6 +230,8 @@ export interface AgentTerminalHandle {
   exitCode?: number | null
   /** Exit signal number once known (POSIX only; undefined on Windows). */
   exitSignal?: number | null
+  /** Active wait_for registrations (skip bookkeeping; empty while idle). */
+  waits: AgentTerminalActiveWait[]
 }
 
 /** Read result shape (mirrors the official tool-pty terminal_read contract). */
@@ -237,6 +246,16 @@ export interface AgentTerminalReadResult {
   lineEnd: number
 }
 
+/** One active wait_for registration on a handle (banner + skip bookkeeping). */
+export interface AgentTerminalActiveWait {
+  /** The needle being awaited (shown on the sidebar wait banner). */
+  needle: string
+  /** Epoch ms when the wait registered (age display / debugging). */
+  since: number
+  /** Flipped by `skipWait()`; the waiting poll returns `skipped` within one tick. */
+  skipped: boolean
+}
+
 /** Outcome of {@link AgentPtyRegistry.waitFor}. */
 export type AgentTerminalWaitResult =
   | {
@@ -276,6 +295,12 @@ export type AgentTerminalWaitResult =
     /** The exit signal name, if the process was killed by a signal. */
     exitSignal?: string | null
   }
+  | {
+    /** The user skipped the wait from the sidebar banner. */
+    kind: 'skipped'
+    /** The needle that was awaited. */
+    needle: string
+  }
 
 /** Snapshot projection of a handle (drops the pty reference and transcript). */
 export function snapshotOf(handle: AgentTerminalHandle): AgentTerminalSnapshot {
@@ -289,6 +314,8 @@ export function snapshotOf(handle: AgentTerminalHandle): AgentTerminalSnapshot {
     out.exitCode = handle.exitCode ?? null
     out.exitSignal = signalNameOf(handle.exitSignal)
   }
+  const active = handle.waits.at(-1)
+  if (active !== undefined) out.waiting = { needle: active.needle, since: active.since }
   return out
 }
 
@@ -349,6 +376,7 @@ export class AgentPtyRegistry {
       pty,
       transcript: '',
       exited: false,
+      waits: [],
     }
     pty.onData((data) => {
       handle.transcript += data
@@ -503,7 +531,8 @@ export class AgentPtyRegistry {
    *   can tell which outcome hit.
    * @param timeoutMs - max wait; default 10000 (10s). Clamped to ≥100ms.
    * @param signal - caller-owned cancellation; aborts the wait re-throwing.
-   * @returns one of `found` / `timeout` / `exited`.
+   * A wait can also be skipped by the user from the sidebar banner (`skipWait`), which resolves it with `{kind:'skipped'}`.
+   * @returns one of `found` / `timeout` / `exited` / `skipped`.
    */
   async waitFor(
     uuid: string,
@@ -531,29 +560,69 @@ export class AgentPtyRegistry {
     if (firstHit !== undefined) {
       return { kind: 'found', needle, line: firstHit.line, column: firstHit.column, match: firstHit.match, elapsedMs: Date.now() - start }
     }
-    // Poll loop: check the transcript every 50ms, exit on match / exit /
-    // abort / timeout. The handle is read live each iteration (its transcript
-    // and exited fields mutate as the pty produces output).
-    while (true) {
-      if (signal?.aborted) signal.throwIfAborted()
-      if (handle.exited) {
-        return { kind: 'exited', needle, exitCode: handle.exitCode ?? null, exitSignal: signalNameOf(handle.exitSignal) }
+    // Register the active wait so the sidebar can show the wait banner (the
+    // snapshot's `waiting` field rides the agent-terminals push). Registered
+    // only after the fast paths: a wait that resolves instantly never
+    // flashes the banner. The notify() makes every push subscriber (the
+    // sidebar view) converge on the new waiting state immediately.
+    const record: AgentTerminalActiveWait = { needle, since: start, skipped: false }
+    handle.waits.push(record)
+    this.notify()
+    try {
+      // Exit outranks a skip in the same tick: `skipWait` flips `record.skipped`
+      // and the next poll observes it, but a pty that died first is the
+      // objective fact (a skip is moot once the process is gone). The user
+      // sees the same three things either way — the banner clears, `skipWait`
+      // reports 0 for the resolved wait, and the tool result says the wait
+      // ended — only the reported `kind` differs (see the design doc's
+      // implementation-deviation record).
+      while (true) {
+        if (signal?.aborted) signal.throwIfAborted()
+        if (handle.exited) {
+          return { kind: 'exited', needle, exitCode: handle.exitCode ?? null, exitSignal: signalNameOf(handle.exitSignal) }
+        }
+        if (record.skipped) {
+          return { kind: 'skipped', needle }
+        }
+        const hit = locateNeedle(handle.transcript, needle, re)
+        if (hit !== undefined) {
+          return { kind: 'found', needle, line: hit.line, column: hit.column, match: hit.match, elapsedMs: Date.now() - start }
+        }
+        if (Date.now() >= deadline) {
+          return { kind: 'timeout', needle, timeoutMs: timeout, totalLines: handle.transcript.split('\n').length }
+        }
+        await new Promise(resolve => {
+          const t = setTimeout(resolve, 50)
+          // Allow the Node process to exit even if the timer is pending.
+          if (typeof t === 'object' && 'unref' in t) (t as { unref: () => void }).unref()
+        })
       }
-      const hit = locateNeedle(handle.transcript, needle, re)
-      if (hit !== undefined) {
-        return { kind: 'found', needle, line: hit.line, column: hit.column, match: hit.match, elapsedMs: Date.now() - start }
-      }
-      if (Date.now() >= deadline) {
-        return { kind: 'timeout', needle, timeoutMs: timeout, totalLines: handle.transcript.split('\n').length }
-      }
-      await new Promise(resolve => {
-        const t = setTimeout(resolve, 50)
-        // Allow the Node process to exit even if the timer is pending.
-        if (typeof t === 'object' && 'unref' in t) (t as { unref: () => void }).unref()
-      })
+    } finally {
+      const index = handle.waits.indexOf(record)
+      if (index !== -1) handle.waits.splice(index, 1)
+      this.notify()
     }
   }
 
+  /**
+   * Mark every active wait on one terminal as skipped (the sidebar banner's
+   * skip button). Each waiting poll loop observes its record's flag within
+   * one 50ms tick and returns `{kind:'skipped'}`. Idempotent: 0 when nothing
+   * is waiting (a stale banner racing a wait that already resolved).
+   * @returns the number of waits that transitioned to skipped.
+   */
+  skipWait(uuid: string): number {
+    const handle = this.expect(uuid)
+    let count = 0
+    for (const record of handle.waits) {
+      if (!record.skipped) {
+        record.skipped = true
+        count += 1
+      }
+    }
+    return count
+  }
+
   /**
    * Send a POSIX signal to a terminal's foreground process.
    *

src/client/EditorHost.tsx

@@ -401,6 +401,7 @@ export function EditorHost(props: {
           onReferenceFile={onReferenceFile}
           onPathRenamed={onPathRenamed}
           onPathDeleted={onPathDeleted}
+          service={ctx.get('betterSidebar')}
         />
       </div>
     )
@@ -482,7 +483,7 @@ export function EditorHost(props: {
             ? <FenceErrorNotice store={store} onDisabled={() => { setReloadSeq(sequence => sequence + 1) }} />
             : <div className={css.editorError}>{load.message}</div>)}
           {!showEmpty && load.status === 'binary' && <BinaryDownload scope={scope} path={path} />}
-          {!showEmpty && load.status === 'ready' && createElement(load.viewer.component, {
+          {!showEmpty && load.status === 'ready' && load.viewer.component !== undefined && createElement(load.viewer.component, {
             ctx, store, scope, path, title,
             viewerId: load.viewer.id,
             content: load.content,
@@ -525,6 +526,7 @@ export function EditorHost(props: {
               onReferenceFile={onReferenceFile}
               onPathRenamed={onPathRenamed}
               onPathDeleted={onPathDeleted}
+              service={ctx.get('betterSidebar')}
             />
           </div>
         )}

src/client/FileTree.tsx

@@ -28,15 +28,17 @@ import {
   IconEditOutline16, IconLinkOutline16, IconTrashOutline16, Menu, Modal, type MenuEntry, type MenuItem, writeClipboard,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import { SiCursor, SiZedindustries } from 'react-icons/si'
-import { VscFile, VscFolder, VscFolderOpened, VscLinkExternal, VscPin, VscPinned } from 'react-icons/vsc'
+import { VscFolderOpened, VscLinkExternal, VscPin, VscPinned } from 'react-icons/vsc'
 import { api, downloadUrl, isOutsideWorkspaceMessage, type FsEntry } from './api.ts'
 import { FenceErrorNotice } from './FenceErrorNotice.tsx'
+import { builtinFileIcon, builtinFolderIcon } from './file-icons.tsx'
 import { IconUploadOutline16, IconVscode16 } from './icons.tsx'
 import { isImeComposition } from './ime-guard.ts'
 import { useSubmenuFlip } from './menu-flip.ts'
 import type { OpenWithTarget } from './open-with.ts'
 import { relativeTo } from './paths.ts'
 import { t } from './locales.ts'
+import type { BetterSidebarService } from './service.ts'
 import type { SidebarStore } from './state.ts'
 import { uploadItemsFromDrop, uploadItemsFromFiles, type UploadItem } from './upload.ts'
 import css from './sidebar.module.css'
@@ -145,9 +147,41 @@ export function FileTree(props: {
   onUploadRequest: (dir: string, items: UploadItem[]) => void
   /** True while an upload is in flight (drops are ignored). */
   busy: boolean
+  /**
+   * The sidebar registry service: when present, externally registered file
+   * icons (`registerFileIcon`) outrank the host's file-type artwork on file rows.
+   * Absent → the built-ins alone (the host always passes it today).
+   */
+  service?: BetterSidebarService
 }) {
-  const { sessionId, cwd, store, expanded, revealed, onToggle, onOpenFile, onOpenFileNewTab, onOpenFileSide, openWithTargets, openWithPinned, openWithSsh, onOpenWith, onToggleOpenWithPin, onReferenceFile, onPathRenamed, onPathDeleted, refreshTick, onUploadRequest, busy } = props
+  const { sessionId, cwd, store, expanded, revealed, onToggle, onOpenFile, onOpenFileNewTab, onOpenFileSide, openWithTargets, openWithPinned, openWithSsh, onOpenWith, onToggleOpenWithPin, onReferenceFile, onPathRenamed, onPathDeleted, refreshTick, onUploadRequest, busy, service } = props
   const [data, setData] = useState<Record<string, LevelData>>({})
+  /**
+   * Registry revision for the file-icon feature: bumps on ANY registry
+   * change (register/dispose of tabs, viewers, or icons — one listener
+   * set) so rows re-resolve their icons. The value itself is unread; the
+   * state bump IS the re-render trigger.
+   */
+  const [, setIconsVersion] = useState(0)
+  useEffect(
+    () => service?.subscribe(() => { setIconsVersion(version => version + 1) }),
+    [service],
+  )
+  /**
+   * One file row's leading glyph. The service resolver owns the whole
+   * chain (registered specific ext → built-in glyph map → registered
+   * global default → stock VscFile, with per-factory crash isolation);
+   * without a service the built-in map alone applies.
+   */
+  const fileRowIcon = (path: string): ReactNode =>
+    service !== undefined ? service.fileIcon(path, 14) : builtinFileIcon(path, 14)
+
+  /**
+   * One directory row's leading glyph: the registered `'folder'` /
+   * `'folder-open'` icon when present, else the built-in VSCodicons glyphs.
+   */
+  const dirRowIcon = (path: string, open: boolean): ReactNode =>
+    service !== undefined ? service.folderIcon(path, open, 14) : builtinFolderIcon(open, 14)
   const dataRef = useRef(data)
   /** The row whose path was just copied ("copied" label replaces its button). */
   const [copiedPath, setCopiedPath] = useState<string | null>(null)
@@ -546,8 +580,8 @@ export function FileTree(props: {
       style={{ paddingLeft: depth * 22 + 6 }}
     >
       {entry.isDir
-        ? (expandedSet.has(entry.path) ? <VscFolderOpened size={14} /> : <VscFolder size={14} />)
-        : <VscFile size={14} />}
+        ? dirRowIcon(entry.path, expandedSet.has(entry.path))
+        : fileRowIcon(entry.path)}
       <input
         ref={renameInputRef}
         className={css.explorerRenameInput}
@@ -625,7 +659,7 @@ export function FileTree(props: {
               onDrop={(event) => { handleDirDrop(event, entry.path) }}
               onContextMenu={(event) => { openRowMenu(event, entry.path, true) }}
             >
-              {isOpen ? <VscFolderOpened size={14} /> : <VscFolder size={14} />}
+              {dirRowIcon(entry.path, isOpen)}
               <span className={css.explorerName}>{entry.name}</span>
               {entry.isSymlink && <IconLinkOutline16 size={12} className={css.explorerSymlink} />}
               {rowActions(entry)}
@@ -658,7 +692,7 @@ export function FileTree(props: {
           onDrop={(event) => { handleFileDrop(event, entry.path) }}
           onContextMenu={(event) => { openRowMenu(event, entry.path, false) }}
         >
-          <VscFile size={14} />
+          {fileRowIcon(entry.path)}
           <span className={css.explorerName}>{entry.name}</span>
           {entry.isSymlink && <IconLinkOutline16 size={12} className={css.explorerSymlink} />}
           {rowActions(entry)}
@@ -703,7 +737,7 @@ export function FileTree(props: {
             onDrop={(event) => { handleDirDrop(event, root) }}
             onContextMenu={(event) => { openRowMenu(event, root, true) }}
           >
-            <VscFolderOpened size={14} />
+            {dirRowIcon(root, true)}
             <span className={css.explorerName}>{baseName(root)}</span>
             {copiedPath === root
               ? <span className={css.explorerCopied}>{t('copied')}</span>

src/client/HtmlPreviewFrame.tsx

@@ -0,0 +1,78 @@
+/**
+ * The one HTML-preview frame both preview surfaces render.
+ *
+ * Why this is not a plain `src` to the `/sidebar/html` route: on DSH Desktop
+ * the host answers 403 `forbidden` to every request that does not carry the
+ * Electron renderer capability (`x-dsh-desktop-renderer`), and the shell
+ * attaches that header only to MAIN-frame and SAME-ORIGIN-subframe traffic
+ * (`requestComesFromRendererOrigin`). A frame sandboxed WITHOUT
+ * allow-same-origin is an opaque origin at request time, so its document
+ * request never carries the capability and the preview shows nothing but the
+ * bare refusal.
+ *
+ * So the document is fetched by the MAIN frame — which does carry it — and
+ * handed to the frame through `srcdoc`. The `sandbox` attribute stays exactly
+ * as before: the preview still runs in an opaque origin, and the route's own
+ * workspace fence still bounds what can be fetched.
+ *
+ * Two consequences worth knowing:
+ * - sandboxed: an opaque origin cannot make network requests either, so a
+ *   self-contained document previews completely while a multi-file one shows
+ *   its markup with the relative assets missing (inlining them is a separate
+ *   job, not this component's);
+ * - unsandboxed (the warned per-surface unlock, or the setting): the srcdoc
+ *   frame inherits the GUI's origin — which is precisely what that escape
+ *   hatch already meant — and there its relative references resolve and load
+ *   like any other same-origin request.
+ *
+ * A fetch that fails hands the frame the route URL instead, so the route's
+ * own answer (its JSON error, or the refusal) stays visible rather than being
+ * replaced by a blank pane.
+ */
+import { useEffect, useState, type ReactNode } from 'react'
+import { HTML_IFRAME_SANDBOX, withPreviewBase } from './html-preview.ts'
+
+/** One preview frame. */
+export function HtmlPreviewFrame(props: {
+  /** The `/sidebar/html/<sessionId>/<path…>` route URL of the SAVED file. */
+  url: string
+  /** Whether the opaque-origin sandbox applies (the default for both surfaces). */
+  sandboxed: boolean
+  className?: string
+  title: string
+}): ReactNode {
+  const { url, sandboxed, className, title } = props
+  const [doc, setDoc] = useState<string | null>(null)
+  const [failed, setFailed] = useState(false)
+  useEffect(() => {
+    const controller = new AbortController()
+    setDoc(null)
+    setFailed(false)
+    void fetch(url, { signal: controller.signal })
+      .then(async (response) => {
+        if (!response.ok) throw new Error(String(response.status))
+        return response.text()
+      })
+      .then((text) => { setDoc(text) })
+      .catch((error: unknown) => {
+        // An abort is this effect's own cleanup, not a failure.
+        if ((error as { name?: string }).name !== 'AbortError') setFailed(true)
+      })
+    return () => { controller.abort() }
+  }, [url])
+  // The delivery path depends only on what we have: the fetched markup, the
+  // route's own answer after a failed fetch, or an empty frame while loading.
+  const delivery = doc !== null
+    ? { srcDoc: withPreviewBase(doc, url) }
+    : failed ? { src: url } : { srcDoc: '' }
+  return (
+    <iframe
+      {...delivery}
+      className={className}
+      sandbox={sandboxed ? HTML_IFRAME_SANDBOX : undefined}
+      referrerPolicy="no-referrer"
+      allow=""
+      title={title}
+    />
+  )
+}

src/client/RenderBoundary.tsx

@@ -26,14 +26,14 @@ export class RenderBoundary extends Component<{ children?: ReactNode; className?
   }
 
   componentDidCatch(error: Error, info: ErrorInfo): void {
-    console.error('[dsh-better-sidebar] render error:', error, info.componentStack)
+    console.error('[dsh-apes-sidebar] render error:', error, info.componentStack)
   }
 
   render(): ReactNode {
     if (this.state.error !== null) {
       return (
         <div className={this.props.className}>
-          <span>dsh-better-sidebar: {this.state.error}</span>
+          <span>dsh-apes-sidebar: {this.state.error}</span>
           <button
             type="button"
             className={css.terminalRetry}

src/client/Sidebar.tsx

@@ -628,8 +628,17 @@ export function Sidebar(props: { ctx: Context; store: SidebarStore }) {
     service.openTab({ type: optionId, title, target: 'bottom' }, { sessionId, cwd })
   }
 
-  /** The tab icon from the tab-type registry. */
+  /**
+   * The tab icon from the tab-type registry. An editor tab WITH a file path
+   * (the per-path windows of split mode — `meta.dir` marks folder windows,
+   * which keep the folder glyph) shows the same file icon the tree row shows
+   * (`fileIcon`, feature `fileIcons`); every other tab uses its tab-type
+   * descriptor icon.
+   */
   const tabIconOf = (tab: SidebarTab): ReactNode => {
+    if (tab.type === 'editor' && tab.path !== undefined && (tab.meta as { dir?: boolean } | undefined)?.dir !== true) {
+      return ctx.get('betterSidebar')?.fileIcon(tab.path, 14) ?? null
+    }
     const descriptor = ctx.get('betterSidebar')?.getTab(tab.type)
     if (descriptor === undefined) return null
     return typeof descriptor.icon === 'function' ? descriptor.icon(14) : descriptor.icon
@@ -641,13 +650,22 @@ export function Sidebar(props: { ctx: Context; store: SidebarStore }) {
    * strip must never break because a plugin's badge computation failed.
    */
   const tabBadgeOf = (tab: SidebarTab): ReactNode => {
+    // Agent-terminal wait indicator (sidebar-internal, deliberately NOT a
+    // TabDescriptor.badge — that API is type-keyed and shared with external
+    // plugins, and cannot address one tab): the agent-terminals push mirrors
+    // the model's live terminal_wait_for into state.agentWaits; an agent tab
+    // whose uuid is waiting shows the hourglass pill.
+    if (isAgentTabId(tab.id)) {
+      const wait = state.agentWaits?.[agentUuidOf(tab.id)]
+      if (wait !== undefined) return <span className={css.tabBadge}>{'⏳'}</span>
+    }
     const descriptor = ctx.get('betterSidebar')?.getTab(tab.type)
     if (descriptor?.badge === undefined) return null
     let value: string | number | null | undefined
     try {
       value = descriptor.badge(ctx, { sessionId, cwd }, state)
     } catch (error) {
-      console.error('[dsh-better-sidebar] tab badge error:', error)
+      console.error('[dsh-apes-sidebar] tab badge error:', error)
       return null
     }
     if (value === null || value === undefined || value === '') return null

src/client/SubagentView.tsx

@@ -704,7 +704,7 @@ export function SubagentView(props: {
     try {
       sessions.openSubagent?.(address)
     } catch (error) {
-      console.error('[dsh-better-sidebar] openSubagent failed:', error)
+      console.error('[dsh-apes-sidebar] openSubagent failed:', error)
     }
   }, [sessions, onOpenChild])
 
@@ -714,7 +714,7 @@ export function SubagentView(props: {
     try {
       sessions.open?.(rootId)
     } catch (error) {
-      console.error('[dsh-better-sidebar] open session failed:', error)
+      console.error('[dsh-apes-sidebar] open session failed:', error)
     }
   }, [sessions, rootId])
 

src/client/TerminalView.tsx

@@ -48,6 +48,7 @@ import {
   shouldActivateTerminalLink,
   openTerminalUrl,
 } from './terminal-links.ts'
+import { TerminalWaitBanner } from './TerminalWaitBanner.tsx'
 import css from './sidebar.module.css'
 
 /** How many consecutive unreasoned failures before showing the error banner. */
@@ -123,6 +124,27 @@ export function TerminalView(props: { scope: SessionScope; tabId: string; store:
   const [fatal, setFatal] = useState<string | null>(null)
   const [depsFatal, setDepsFatal] = useState<TerminalDepsInfo | null>(null)
   const [lastUrl, setLastUrl] = useState<string | null>(null)
+  // Agent terminals only: the model's active terminal_wait_for (mirrored
+  // from the host's agent-terminals push into the store) drives the wait
+  // banner. Read + subscribe like the font prefs above; the banner vanishes
+  // when the host's push drops the waiting field (skip / exit / abort all
+  // converge through the same push). getSnapshot() is {sessionId, state?,
+  // prefs} — the state may be briefly undefined around session switches.
+  const agentUuid = isAgentTabId(tabId) ? agentUuidOf(tabId) : null
+  const [waiting, setWaiting] = useState<{ needle: string; since: number } | undefined>(undefined)
+  useEffect(() => {
+    if (agentUuid === null) return
+    const read = (): void => {
+      const next = store.getSnapshot().state?.agentWaits?.[agentUuid]
+      setWaiting(prev => {
+        const nextValue = next === undefined ? undefined : { needle: next.needle, since: next.since }
+        if (prev?.needle === nextValue?.needle && prev?.since === nextValue?.since) return prev
+        return nextValue
+      })
+    }
+    read()
+    return store.subscribe(read)
+  }, [agentUuid, store])
   const connectRef = useRef<(() => void) | null>(null)
 
   useEffect(() => {
@@ -267,7 +289,7 @@ export function TerminalView(props: { scope: SessionScope; tabId: string; store:
         failures += 1
         if (failures >= FAILURE_LIMIT) {
           const detail = event.reason !== '' ? ` (${event.code}: ${event.reason})` : ` (${event.code})`
-          console.error('[dsh-better-sidebar] terminal connection failed:', event.code, event.reason, url)
+          console.error('[dsh-apes-sidebar] terminal connection failed:', event.code, event.reason, url)
           setFatal(`${t('terminalConnectFailed')}${detail}`)
           return
         }
@@ -337,7 +359,7 @@ export function TerminalView(props: { scope: SessionScope; tabId: string; store:
         fit.fit()
         sendResize()
       } catch (error) {
-        console.error('[dsh-better-sidebar] xterm open failed:', error)
+        console.error('[dsh-apes-sidebar] xterm open failed:', error)
       }
     })
 
@@ -386,6 +408,12 @@ export function TerminalView(props: { scope: SessionScope; tabId: string; store:
 
   return (
     <div className={css.terminalWrap}>
+      {agentUuid !== null && waiting !== undefined && (
+        <TerminalWaitBanner
+          needle={waiting.needle}
+          onSkip={() => { void api.agentSkipWait(agentUuid).catch(() => { /* 跳过失败时 banner 留存，可重试 */ }) }}
+        />
+      )}
       {depsFatal !== null && (
         <TerminalDepsBanner deps={depsFatal} onRetry={() => { setDepsFatal(null); connectRef.current?.() }} />
       )}

src/client/TerminalWaitBanner.tsx

@@ -0,0 +1,43 @@
+/**
+ * The "Agent 正在等待 {needle}" wait banner: rendered at the top of an
+ * agent-owned terminal's view while the model blocks in terminal_wait_for.
+ * The skip button asks the host to abort every active wait on the terminal
+ * (`agent-pty.skip-wait`); the banner disappears when the host's next
+ * agent-terminals push drops the waiting field — no optimistic UI. Kept in
+ * its own module (no xterm imports) so jsdom tests can render it directly.
+ */
+import { t } from './locales.ts'
+import css from './sidebar.module.css'
+
+/** Cap the needle shown inline; the full text rides the title tooltip. */
+const NEEDLE_DISPLAY_CAP = 80
+
+/** Truncate one needle for inline display (title attr carries the full text).
+ *  Cut by Unicode code points, not UTF-16 code units — a naive slice can split
+ *  a surrogate pair at the cutoff and render a dangling replacement char. */
+export function truncateNeedle(needle: string): string {
+  const points = Array.from(needle)
+  return points.length > NEEDLE_DISPLAY_CAP
+    ? `${points.slice(0, NEEDLE_DISPLAY_CAP - 1).join('')}…`
+    : needle
+}
+
+export function TerminalWaitBanner(props: { needle: string; onSkip: () => void }) {
+  const { needle, onSkip } = props
+  return (
+    <div className={css.terminalWaitBanner}>
+      <span
+        className={css.terminalWaitNeedle}
+        title={needle}
+        role="status"
+        aria-live="polite"
+        aria-label={t('terminalWaitBanner', { needle })}
+      >
+        {t('terminalWaitBanner', { needle: truncateNeedle(needle) })}
+      </span>
+      <button type="button" className={css.terminalRetry} onClick={onSkip}>
+        {t('terminalSkipWait')}
+      </button>
+    </div>
+  )
+}

src/client/TextEditor.tsx

@@ -36,7 +36,7 @@ import { LazyMermaidMarkdown, MarkdownDocument, type MarkdownHtmlMedia } from '.
 import { MdToc } from './md-toc.tsx'
 import { splitMermaidBlocks } from './mermaid-blocks.ts'
 import { t } from './locales.ts'
-import { HTML_IFRAME_SANDBOX } from './html-preview.ts'
+import { HtmlPreviewFrame } from './HtmlPreviewFrame.tsx'
 import type { EditorToolbarState, FileViewerProps } from './service.ts'
 import css from './sidebar.module.css'
 
@@ -545,16 +545,14 @@ export function TextEditor(props: FileViewerProps) {
             onUnlock={() => { setLocalUnlock(true) }}
             onRestore={() => { setLocalUnlock(false) }}
           />
-          {/* Route-src (never srcdoc — a srcdoc frame inherits the parent
-              origin when unsandboxed; the route URL keeps the frame
-              cross-origin by construction). The preview shows the SAVED
-              file; the draft is only visible in edit mode. */}
-          <iframe
+          {/* The preview shows the SAVED file; the draft is only visible in
+              edit mode. HtmlPreviewFrame owns both the delivery path
+              (main-frame fetch -> srcdoc, which a sandboxed frame could not
+              reach on its own) and the sandbox tokens. */}
+          <HtmlPreviewFrame
             className={css.editorHtml}
-            src={htmlUrl(scope, path)}
-            sandbox={htmlNoSandbox ? undefined : HTML_IFRAME_SANDBOX}
-            referrerPolicy="no-referrer"
-            allow=""
+            url={htmlUrl(scope, path)}
+            sandboxed={!htmlNoSandbox}
             title={path}
           />
         </>

src/client/TreePanel.tsx

@@ -19,6 +19,7 @@ import { useEffect, useRef, useState, type InputHTMLAttributes } from 'react'
 import clsx from 'clsx'
 import { IconFolderOpen16, IconRefreshOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
 import { api } from './api.ts'
+import type { BetterSidebarService } from './service.ts'
 import type { SidebarStore } from './state.ts'
 import { FileTree } from './FileTree.tsx'
 import { IconUploadOutline16 } from './icons.tsx'
@@ -70,8 +71,10 @@ export function TreePanel(props: {
   /** Full-window presentation: the panel fills its host instead of docking
    *  at a fixed width. */
   full?: boolean
+  /** The sidebar registry service (file-icon registrations; passed through to FileTree). */
+  service?: BetterSidebarService
 }) {
-  const { sessionId, cwd, store, expanded, revealed, onToggle, onOpenFile, onOpenFileNewTab, onOpenFileSide, openWithTargets, openWithPinned, openWithSsh, onOpenWith, onToggleOpenWithPin, onReferenceFile, onPathRenamed, onPathDeleted, full } = props
+  const { sessionId, cwd, store, expanded, revealed, onToggle, onOpenFile, onOpenFileNewTab, onOpenFileSide, openWithTargets, openWithPinned, openWithSsh, onOpenWith, onToggleOpenWithPin, onReferenceFile, onPathRenamed, onPathDeleted, full, service } = props
   const [query, setQuery] = useState('')
   const [results, setResults] = useState<{ matches: string[]; truncated: boolean } | null>(null)
   const [error, setError] = useState<string | null>(null)
@@ -261,6 +264,7 @@ export function TreePanel(props: {
           refreshTick={refreshTick}
           onUploadRequest={startUpload}
           busy={busy}
+          service={service}
         />
       ) : (
         <div className={css.explorerBody}>

src/client/apes/icons.tsx

@@ -0,0 +1,50 @@
+/**
+ * Tab glyphs for the apes tabs (智能体 / 应用 / 画像).
+ *
+ * These follow the SAME recipe as this repo's own icon set in
+ * `src/client/icons.tsx` — the one the sidebar already uses for 终端 /
+ * 浏览器 / 文件变动: a 16×16 viewBox whose artwork spans 1.5–14.5, a 1.5px
+ * `currentColor` stroke, round caps/joins, `fill: none`.
+ *
+ * That recipe is what makes an icon sit at the native visual weight in the
+ * `+` new-tab menu and the right-panel tile grid: DSH's own glyphs fill
+ * ~92–96% of the box, so artwork padded any tighter renders visibly small
+ * next to them.
+ *
+ * (An earlier revision drew these as fill-only paths spanning only 10–12 of
+ * the 16 units — that is why they read as a separate, lighter family.)
+ */
+import type { ReactNode } from 'react'
+
+/** Agent glyph: a rounded robot head with two fill eyes. */
+export function IconAgentOutline16({ size = 16, className }: { size?: number; className?: string }): ReactNode {
+  return (
+    <svg width={size} height={size} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg" className={className}>
+      <rect x="1.5" y="3" width="13" height="11.5" rx="4.2" stroke="currentColor" strokeWidth="1.5" />
+      <circle cx="5.8" cy="8.6" r="1.25" fill="currentColor" />
+      <circle cx="10.2" cy="8.6" r="1.25" fill="currentColor" />
+    </svg>
+  )
+}
+
+/** Apps glyph: a 2×2 grid of rounded squares. */
+export function IconAppsOutline16({ size = 16, className }: { size?: number; className?: string }): ReactNode {
+  return (
+    <svg width={size} height={size} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg" className={className}>
+      <rect x="1.5" y="1.5" width="5.5" height="5.5" rx="1.8" stroke="currentColor" strokeWidth="1.5" />
+      <rect x="9" y="1.5" width="5.5" height="5.5" rx="1.8" stroke="currentColor" strokeWidth="1.5" />
+      <rect x="1.5" y="9" width="5.5" height="5.5" rx="1.8" stroke="currentColor" strokeWidth="1.5" />
+      <rect x="9" y="9" width="5.5" height="5.5" rx="1.8" stroke="currentColor" strokeWidth="1.5" />
+    </svg>
+  )
+}
+
+/** Profile glyph: a head over shoulders. */
+export function IconUserOutline16({ size = 16, className }: { size?: number; className?: string }): ReactNode {
+  return (
+    <svg width={size} height={size} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg" className={className}>
+      <circle cx="8" cy="4.9" r="3.4" stroke="currentColor" strokeWidth="1.5" />
+      <path d="M1.5 14.5c0-3.3 2.8-5.3 6.5-5.3s6.5 2 6.5 5.3" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+    </svg>
+  )
+}

src/client/apes/index.ts

@@ -0,0 +1,43 @@
+/**
+ * apes:* information-layer tabs — the fork's own contribution on top of the
+ * upstream dsh-better-sidebar. Three tabs ship (agents / apps / profile);
+ * `apes:tasks` was removed (C6) because it overlaps the official DSH session
+ * tree in the native sidebar, and `messages` is deferred (no DSH
+ * message-stream API yet — tracked separately).
+ *
+ * Isolated under `src/client/apes/` so the upstream `builtins/` tree stays
+ * untouched: cherry-picking upstream releases only has to keep the single
+ * `registerApesTabs(...)` call site in `index.tsx` (see D1 = module B).
+ *
+ * Every descriptor is registered through the same `BetterSidebarService`
+ * the builtins use (dogfood), so the apes tabs get the full sidebar
+ * lifecycle for free: + menu, enable/disable switches, badge pills,
+ * dedupe/focus, and HMR-safe disposal via the returned disposer.
+ */
+import type { Context } from '../../context-types.ts'
+import type { BetterSidebarService } from '../service.ts'
+import { apesTabs } from './tabs.tsx'
+
+// Re-exported so index.tsx can register the apes dictionaries + attach the
+// locale service in one import (keeps the apes module self-contained).
+export { APES_LOCALE_NS, apesZh, apesEn, attachApesLocale } from './locales.ts'
+
+/**
+ * Register the apes:* tabs with the sidebar service. Returns a disposer that
+ * unregisters all of them (cordis auto-invokes it on fiber disposal, so HMR
+ * re-activation re-registers cleanly — same contract as registerBuiltins).
+ */
+export function registerApesTabs(
+  _ctx: Context,
+  service: BetterSidebarService,
+): () => void {
+  const disposers: (() => void)[] = []
+  for (const tab of apesTabs) {
+    disposers.push(service.registerTab(tab))
+  }
+  return () => {
+    for (const d of disposers) {
+      try { d() } catch { /* already disposed */ }
+    }
+  }
+}

src/client/apes/locales.ts

@@ -0,0 +1,87 @@
+/**
+ * apes:* tab i18n — isolated from the upstream `betterSidebar` locale
+ * namespace (D1 = module B). The fork keeps its own `apes` namespace and
+ * its own `t()` so that adding apes keys never touches the upstream
+ * `locales.ts` (whose `CopyKey = keyof typeof zh` is closed over its own
+ * dicts). The `t()` mirrors the upstream implementation's resolution order
+ * (active-locale chain → key fallback) but reads the apes dicts; it is NOT
+ * wired to the better-locale override store in Phase 1 (those third-language
+ * overrides ride the lazy `locale` chunk that only covers `betterSidebar`
+ * entries — apes keys fall back to zh/en, which is acceptable for the
+ * placeholder round and gets the override integration in Phase 2).
+ */
+
+/** The apes locale namespace (registered with ctx.locale under this key). */
+export const APES_LOCALE_NS = 'apes'
+
+/** The zh dictionary (source of truth). */
+export const apesZh = {
+  // View titles
+  apesAgentsTitle: '智能体',
+  apesAppsTitle: '应用',
+  apesProfileTitle: '画像',
+  // Agents view
+  apesAgentsEmpty: '当前会话没有子智能体',
+  apesAgentsRoot: '主智能体',
+  apesAgentRunning: '运行中',
+  apesAgentInactive: '空闲',
+  apesAgentOneShot: '一次性',
+  apesAgentContinuable: '可续',
+  // Profile view
+  apesProfileCurrent: '当前会话',
+  apesProfileCwd: '工作目录',
+  apesProfileNoCwd: '未知',
+  apesProfileRunning: '运行中',
+  apesProfileIdle: '空闲',
+  // Apps view
+  apesAppsNoFeed: '当前 DSH 版本未提供工作区应用数据源',
+  apesAppsWorkspace: '工作区',
+} as const
+
+/** The en dictionary (checked against zh — every zh key must appear here). */
+export const apesEn: Record<keyof typeof apesZh, string> = {
+  apesAgentsTitle: 'Agents',
+  apesAppsTitle: 'Apps',
+  apesProfileTitle: 'Profile',
+  apesAgentsEmpty: 'No subagents in this session',
+  apesAgentsRoot: 'Main agent',
+  apesAgentRunning: 'running',
+  apesAgentInactive: 'idle',
+  apesAgentOneShot: 'one-shot',
+  apesAgentContinuable: 'continuable',
+  apesProfileCurrent: 'Current session',
+  apesProfileCwd: 'Working directory',
+  apesProfileNoCwd: 'unknown',
+  apesProfileRunning: 'running',
+  apesProfileIdle: 'idle',
+  apesAppsNoFeed: 'This DSH version exposes no workspace-app feed',
+  apesAppsWorkspace: 'Workspace',
+}
+
+export type ApesCopyKey = keyof typeof apesZh
+
+/** Resolve the currently active DSH locale ('zh' | 'en' today). */
+export function attachApesLocale(service: { getSnapshot(): { active: string } } | undefined): void {
+  apesLocaleService = service
+}
+
+let apesLocaleService: { getSnapshot(): { active: string } } | undefined
+
+/**
+ * Translate an apes key. Resolution order: active-locale chain (zh dict when
+ * the DSH preference is zh, en dict otherwise) → key fallback (shows the key
+ * itself rather than `undefined`). Mirrors the upstream t() minus the
+ * better-locale override (Phase 2).
+ */
+export function t(key: ApesCopyKey, params?: Record<string, string | number>): string {
+  const active = apesLocaleService?.getSnapshot().active ?? 'zh'
+  const dict = active.toLowerCase().startsWith('zh') ? apesZh : apesEn
+  let text: string | undefined = dict[key]
+  if (text === undefined) text = key
+  if (params !== undefined) {
+    for (const [name, value] of Object.entries(params)) {
+      text = text.replaceAll(`{${name}}`, String(value))
+    }
+  }
+  return text
+}

src/client/apes/tabs.tsx

@@ -0,0 +1,237 @@
+/**
+ * apes:* tab views (D2 = data wiring). Each tab reads live data from the
+ * sessions list feed (`ctx.sessions.list`) via `useSyncExternalStore` and
+ * reuses the fork's PURE lineage/job helpers — these are framework-free and
+ * live outside `builtins/`, so importing them does not couple the apes module
+ * to upstream UI and survives cherry-picks.
+ *
+ * Three information-layer tabs (C6: `apes:tasks` removed — it overlaps the
+ * official DSH session tree in the native sidebar):
+ *   - apes:agents  → the subagent topology rooted at the main agent of the
+ *                    current session (rootAncestor + per-parent catalogs).
+ *   - apes:apps    → no DSH host feed today: shows the workspace (cwd) of the
+ *                    current session, otherwise an honest "no feed" note.
+ *   - apes:profile → the current session's summary row (title, cwd, running).
+ *
+ * Visual unity (C7): colors use the DSW design-token aliases
+ * (`--dsw-alias-*`) so the apes panels match the native DSH sidebar
+ * surface; the runtime defines these on :root. Font sizes / spacing /
+ * radius stay inline (DSH exposes no public `--ds-*` geometry alias for
+ * plugin panels — its own vendor bundles inline those too).
+ *
+ * Data sources (structural mirror — runtime provided by the DSH host):
+ *   - `ctx.sessions.list.getSnapshot()` → { current, byId, subagentsByParent? };
+ *     `subscribe(cb)` is uSES-safe.
+ *   - `scope.sessionId` = the currently-open session.
+ */
+import { useCallback, useMemo, useState, type CSSProperties } from 'react'
+import { useSyncExternalStore } from 'react'
+import { IconAgentOutline16, IconAppsOutline16, IconUserOutline16 } from './icons.tsx'
+import type { TabComponentProps, TabDescriptor } from '../service.ts'
+import type {
+  SidebarSessionList,
+  SidebarSessionSummary,
+  SidebarSubagentCatalog,
+  SidebarSubagentChildEntry,
+} from '../../context-types.ts'
+import { rootAncestor, isSideThreadSummary } from '../subagent-lineage.ts'
+import { t } from './locales.ts'
+
+/**
+ * DSW design-token color aliases. The DSH runtime defines these on :root
+ * (same set the native dsh-client-ui-* vendor bundles consume). We reference
+ * them by name via `var(...)` with a literal fallback so the panels still
+ * render in a non-DSH context (unit harness) with a sane dark palette.
+ */
+const DSW = {
+  bgBase: 'var(--dsw-alias-bg-base, #1a1a1a)',
+  bgLayer1: 'var(--dsw-alias-bg-layer-1, #202020)',
+  borderL1: 'var(--dsw-alias-border-l1, #2a2a2a)',
+  borderL2: 'var(--dsw-alias-border-l2, #303030)',
+  labelPrimary: 'var(--dsw-alias-label-primary, #e8e8e8)',
+  labelSecondary: 'var(--dsw-alias-label-secondary, #a0a0a0)',
+  labelTertiary: 'var(--dsw-alias-label-tertiary, #7a7a7a)',
+  success: 'var(--dsw-alias-state-success-primary, #52c41a)',
+  interactiveHover: 'var(--dsw-alias-interactive-bg-hover, rgba(255,255,255,0.06))',
+} as const
+
+/** Shared inline styles (KISS: one object, no CSS module). Colors via DSW. */
+const S: Record<string, CSSProperties> = {
+  body: { padding: 12, display: 'flex', flexDirection: 'column', gap: 12 },
+  title: { margin: 0, fontSize: 14, fontWeight: 600, color: DSW.labelPrimary },
+  hint: { margin: 0, fontSize: 12, color: DSW.labelTertiary },
+  list: { display: 'flex', flexDirection: 'column', gap: 8 },
+  card: { border: `1px solid ${DSW.borderL1}`, borderRadius: 8, padding: 10, display: 'flex', flexDirection: 'column', gap: 6, background: DSW.bgLayer1 },
+  cardRow: { display: 'flex', alignItems: 'center', gap: 8 },
+  cardLabel: { fontSize: 13, fontWeight: 500, flex: 1, minWidth: 0, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap', color: DSW.labelPrimary },
+  cardSecondary: { fontSize: 11, color: DSW.labelSecondary, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' },
+  badge: { fontSize: 11, color: DSW.labelTertiary, flexShrink: 0 },
+}
+
+/** A small colored status dot (self-contained, not the builtin StateDot). */
+function Dot(props: { color: string }) {
+  const style: CSSProperties = {
+    width: 8, height: 8, borderRadius: '50%', background: props.color, flexShrink: 0, display: 'inline-block',
+  }
+  return <span aria-hidden style={style} />
+}
+
+/** Subscribe to the sessions list feed (uSES-safe). Returns the live snapshot. */
+function useSessionList(ctx: TabComponentProps['ctx']): SidebarSessionList {
+  const sessions = ctx.sessions
+  return useSyncExternalStore(
+    useMemo(() => (callback: () => void) => sessions.list.subscribe(callback), [sessions]),
+    useCallback(() => sessions.list.getSnapshot(), [sessions]),
+  )
+}
+
+/** One level of the subagent topology (rooted at the main agent). */
+function agentChildren(
+  byId: Readonly<Record<string, SidebarSessionSummary>>,
+  parentSessionId: string,
+): SidebarSessionSummary[] {
+  return Object.values(byId).filter(
+    s => s.origin === 'subagent' && s.parentId === parentSessionId && !isSideThreadSummary(s),
+  )
+}
+
+/** apes:agents — the subagent topology of the current session's tree. */
+function ApesAgentsView(props: TabComponentProps) {
+  const list = useSessionList(props.ctx)
+  const { byId, subagentsByParent } = list
+  const rootId = useMemo(() => rootAncestor(byId, props.scope.sessionId), [byId, props.scope.sessionId])
+  const rootSummary = rootId === undefined ? undefined : byId[rootId]
+  const rootCatalog = rootId === undefined ? undefined : subagentsByParent?.[rootId]
+
+  // The topology: the main agent + its direct subagent children (one level,
+  // with per-child activity). A lazy catalog (subagentsByParent) is preferred
+  // for the child list when present; otherwise fall back to durable byId rows.
+  // (`.filter` does not narrow a union — narrow explicitly to child entries.)
+  const children: SidebarSubagentChildEntry[] = (rootCatalog?.entries ?? [])
+    .filter((e): e is SidebarSubagentChildEntry => e.kind === 'child')
+    .concat(rootCatalog === undefined
+      ? agentChildren(byId, rootId ?? '').map<SidebarSubagentChildEntry>(s => ({
+        kind: 'child', id: s.id, mode: 'continuable',
+        activity: s.running === true ? 'running' : 'inactive',
+        label: s.displayTitle, hasChildren: agentChildren(byId, s.id).length > 0,
+      }))
+      : [])
+
+  return (
+    <div style={S.body}>
+      <h2 style={S.title}>{t('apesAgentsTitle')}</h2>
+      {rootSummary === undefined && children.length === 0
+        ? <p style={S.hint}>{t('apesAgentsEmpty')}</p>
+        : (
+          <div style={S.list}>
+            {/* Root (main agent) node */}
+            {rootSummary !== undefined && (
+              <div style={S.card}>
+                <div style={S.cardRow}>
+                  <Dot color={rootSummary.running === true ? DSW.success : DSW.labelTertiary} />
+                  <span style={S.cardLabel} title={rootSummary.displayTitle}>{t('apesAgentsRoot')}: {rootSummary.displayTitle}</span>
+                </div>
+                <div style={S.cardRow}>
+                  <span style={S.badge}>{rootSummary.running === true ? t('apesAgentRunning') : t('apesAgentInactive')}</span>
+                </div>
+              </div>
+            )}
+            {/* Direct subagent children */}
+            {children.map(entry => {
+              const summary = byId[entry.id]
+              const running = entry.activity === 'running'
+              const label = entry.label ?? summary?.displayTitle ?? entry.id
+              return (
+                <div key={entry.id} style={{ ...S.card, marginLeft: 14, borderLeft: `2px solid ${DSW.borderL2}` }}>
+                  <div style={S.cardRow}>
+                    <Dot color={running ? DSW.success : DSW.labelTertiary} />
+                    <span style={S.cardLabel} title={label}>{label}</span>
+                  </div>
+                  <div style={S.cardRow}>
+                    <span style={S.cardSecondary}>
+                      {entry.mode === 'one-shot' ? t('apesAgentOneShot') : t('apesAgentContinuable')}
+                      {' · '}
+                      {running ? t('apesAgentRunning') : t('apesAgentInactive')}
+                    </span>
+                  </div>
+                </div>
+              )
+            })}
+          </div>
+        )}
+    </div>
+  )
+}
+
+/** apes:profile — the current session's identity (title, cwd, running state). */
+export function ApesProfileView(props: TabComponentProps) {
+  const list = useSessionList(props.ctx)
+  const current = list.current
+  const summary = current === undefined ? undefined : list.byId[current]
+  const cwd = summary?.cwd ?? props.scope.cwd
+
+  return (
+    <div style={S.body}>
+      <h2 style={S.title}>{t('apesProfileTitle')}</h2>
+      {summary === undefined
+        ? <p style={S.hint}>{t('apesProfileNoCwd')}</p>
+        : (
+          <div style={S.list}>
+            <div style={S.card}>
+              <div style={S.cardRow}>
+                <Dot color={summary.running === true ? DSW.success : DSW.labelTertiary} />
+                <span style={S.cardLabel} title={summary.displayTitle}>{t('apesProfileCurrent')}</span>
+              </div>
+              <div style={S.cardRow}>
+                <span style={S.badge}>{summary.running === true ? t('apesProfileRunning') : t('apesProfileIdle')}</span>
+              </div>
+            </div>
+            <div style={S.card}>
+              <div style={S.cardRow}>
+                <span style={S.cardLabel}>{summary.displayTitle}</span>
+              </div>
+              <div style={S.cardRow}>
+                <span style={S.cardSecondary}>{t('apesProfileCwd')}: {cwd ?? t('apesProfileNoCwd')}</span>
+              </div>
+            </div>
+          </div>
+        )}
+    </div>
+  )
+}
+
+/** apes:apps — no DSH host feed today; shows the current workspace (cwd). */
+function ApesAppsView(props: TabComponentProps) {
+  const list = useSessionList(props.ctx)
+  const current = list.current
+  const summary = current === undefined ? undefined : list.byId[current]
+  const cwd = summary?.cwd ?? props.scope.cwd
+
+  return (
+    <div style={S.body}>
+      <h2 style={S.title}>{t('apesAppsTitle')}</h2>
+      <p style={S.hint}>{t('apesAppsNoFeed')}</p>
+      <div style={S.card}>
+        <div style={S.cardRow}>
+          <span style={S.cardLabel}>{t('apesAppsWorkspace')}</span>
+        </div>
+        <div style={S.cardRow}>
+          <span style={S.cardSecondary}>{cwd ?? t('apesProfileNoCwd')}</span>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+/**
+ * The three apes:* tab descriptors (C6: `apes:tasks` removed — overlaps the
+ * official DSH session tree). Order 901-903: agents/apps/profile. Each is
+ * already shaped as `TabDescriptor` (component + single-instance + icon
+ * element + i18n title function) so `registerApesTabs` can hand them straight
+ * to `service.registerTab`. Information-layer tabs are single-instance.
+ */
+export const apesTabs: TabDescriptor[] = [
+  { id: 'apes:agents', title: () => t('apesAgentsTitle'), icon: (size: number) => <IconAgentOutline16 size={size} />, order: 60, single: true, component: ApesAgentsView },
+  { id: 'apes:apps', title: () => t('apesAppsTitle'), icon: (size: number) => <IconAppsOutline16 size={size} />, order: 65, single: true, component: ApesAppsView },
+  { id: 'apes:profile', title: () => t('apesProfileTitle'), icon: (size: number) => <IconUserOutline16 size={size} />, order: 70, single: true, component: ApesProfileView },
+]

src/client/api.ts

@@ -346,6 +346,10 @@ export const api = {
   /** Release an agent terminal by uuid (tab closed while WS was down). */
   agentPtyClose: (uuid: string) =>
     call<{ ok: true }>('agent-pty.close', { uuid }),
+  /** Skip every active terminal_wait_for on one agent terminal (the wait
+   *  banner's skip button). Idempotent: {skipped:0} when none is active. */
+  agentSkipWait: (uuid: string) =>
+    call<{ ok: true; skipped: number }>('agent-pty.skip-wait', { uuid }),
   /** Terminal dependency status (issue #140): after a WS close 1011 with
    *  reason `pty-deps-missing` the view fetches the full repair details here
    *  (the close reason itself is capped at 123 bytes). */

src/client/builtins/tab-icons.module.css

@@ -0,0 +1,39 @@
+/*
+ * Colors for the built-in tab glyphs (src/client/builtins/tab-icons.tsx).
+ *
+ * Every declaration resolves to a `--dsw-alias-*` token, so all skins stay in
+ * charge — including the token's own fallback chain, which keeps the glyph
+ * legible on a host that does not define the brand/state families. The plugin
+ * never writes a color literal here; `tests/theme.spec.ts` enforces both
+ * halves of that rule.
+ *
+ * The chips sit on the panel surface, so a token that is itself translucent
+ * would wash out at 14px; each rule therefore prefers an opaque state/brand
+ * token and falls back to the primary ink.
+ */
+
+.files {
+  color: var(--dsw-alias-brand-primary, var(--dsw-alias-label-primary));
+}
+
+.changes {
+  color: var(--dsw-alias-state-success-primary, var(--dsw-alias-brand-primary, var(--dsw-alias-label-primary)));
+}
+
+.tasks {
+  color: var(--dsw-alias-state-warn-primary, var(--dsw-alias-label-primary));
+}
+
+.sidechat {
+  color: var(--dsw-alias-state-business-primary, var(--dsw-alias-brand-primary, var(--dsw-alias-label-primary)));
+}
+
+.terminal {
+  /* The shell chip is ink, not accent. Its glyph is the widest in the set and
+     renders a step smaller than its siblings (see tab-icons.tsx). */
+  color: var(--dsw-alias-label-primary);
+}
+
+.browser {
+  color: var(--dsw-alias-state-business-primary, var(--dsw-alias-brand-primary, var(--dsw-alias-label-primary)));
+}

src/client/builtins/tab-icons.tsx

@@ -0,0 +1,71 @@
+/**
+ * The built-in tab glyphs, in color.
+ *
+ * Every built-in tab type and the incoming 8th (changes) declare their icon
+ * here, so the three surfaces that draw a tab's glyph — the bottom workbench's
+ * tab strip, the native right Sidebar's guide capsules and its tab chips — all
+ * read the same colorful glyph from `descriptor.icon`.
+ *
+ * The color always arrives from a theme token, never from the plugin: the
+ * glyph is a VSCodicon drawn in `currentColor`, and the wrapper class supplies
+ * that color. A skin therefore keeps control of everything (the guide's §12);
+ * this module is what `tests/theme.spec.ts` checks for color literals.
+ *
+ * `files` is the one exception in kind rather than in color: it renders DSH's
+ * own folder artwork (`FileTypeIcon`), matching the file rows this tab shows.
+ */
+import type { ReactNode } from 'react'
+import { FileTypeIcon } from '@deepseek-ai/dsh-client-ui-primitives'
+import styles from './tab-icons.module.css'
+import {
+  VscCommentDiscussion,
+  VscGitCommit,
+  VscGlobe,
+  VscLayers,
+  VscTerminal,
+} from 'react-icons/vsc'
+/** The styled wrapper classes; typed so a renamed rule fails the build. */
+const css = styles as Record<'files' | 'changes' | 'tasks' | 'sidechat' | 'terminal' | 'browser', string>
+
+/** One tab type's glyph, sized by the caller's surface (14px in a strip). */
+export type TabIcon = (size: number) => ReactNode
+
+/** Surround a glyph with the class that hands it its token-driven color. */
+function themed(className: string, glyph: ReactNode): ReactNode {
+  return <span className={className}>{glyph}</span>
+}
+
+/** The Files tab: the host's folder artwork, like the rows it opens. */
+export const filesTabIcon: TabIcon = (size) => (
+  <span className={css.files}>
+    <FileTypeIcon kind="folder" size={size} />
+  </span>
+)
+
+/** Changes / diff: the commit glyph, green like the diff affordances. */
+export const changesTabIcon: TabIcon = (size) =>
+  themed(css.changes, <VscGitCommit size={size} />)
+
+/**
+ * Tasks (subagents and background jobs) — the live-activity amber. The glyph
+ * is layered sheets, not a checklist: this page lists RUNNING work (subagent
+ * sessions plus the host's background jobs), not a to-do list.
+ */
+export const tasksTabIcon: TabIcon = (size) =>
+  themed(css.tasks, <VscLayers size={size} />)
+
+/** Side chat — the conversational/secondary accent. */
+export const sidechatTabIcon: TabIcon = (size) =>
+  themed(css.sidechat, <VscCommentDiscussion size={size} />)
+
+/**
+ * Terminal — primary ink, the shell is text. Rendered one step down from the
+ * strip's 14px: the VSCodicon terminal is a wide filled rectangle and read
+ * heavier than its neighbours at full size.
+ */
+export const terminalTabIcon: TabIcon = (size) =>
+  themed(css.terminal, <VscTerminal size={Math.max(10, Math.round(size * 0.85))} />)
+
+/** Browser — the same secondary accent as the side chat's sibling surfaces. */
+export const browserTabIcon: TabIcon = (size) =>
+  themed(css.browser, <VscGlobe size={size} />)

src/client/builtins/tabs.tsx

@@ -8,8 +8,11 @@
  * `browser:<n>` the same way (no quota). The editor IS the files window
  * (the old standalone explorer merged into it).
  */
-import { IconCodeOutline16, IconFolderOpen16, IconNewChatOutline16, IconPanelLeftOutline16, IconThinkOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
+import { IconCodeOutline16, IconPanelLeftOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { Context } from '../../context-types.ts'
+import {
+  browserTabIcon, changesTabIcon, filesTabIcon, sidechatTabIcon, tasksTabIcon, terminalTabIcon,
+} from './tab-icons.tsx'
 import { allLeaves, isAgentTabId, type SidebarState } from '../state.ts'
 import { t } from '../locales.ts'
 import { openSidebarFile } from '../intercept.tsx'
@@ -22,7 +25,6 @@ import { SubagentView } from '../SubagentView.tsx'
 import { consumeSidechatSeed, SideChatView, sidechatThreadIdOf } from '../SideChatView.tsx'
 import { api } from '../api.ts'
 import { BrowserView } from '../BrowserView.tsx'
-import { IconTerminalOutline16, IconDiffOutline16, IconGlobeOutline16 } from '../icons.tsx'
 import { TERMINAL_FONT_SIZE_MAX, TERMINAL_FONT_SIZE_MIN } from '../../prefs-shared.ts'
 import type { ComponentType } from 'react'
 import type { SessionScope } from '../api.ts'
@@ -82,11 +84,12 @@ export function builtinTabs(ctx: Context, options: BuiltinTabOptions = {}): read
   return [
     {
       id: 'editor',
+      description: () => t('guideDescFiles'),
       // The single files window: an editor tab with no path IS the file
       // explorer (empty hint + docked tree); with a path it previews/edits
       // the file. Visible in the + menu in the explorer's old slot.
       title: () => t('files'),
-      icon: (size: number) => <IconFolderOpen16 size={size} />,
+      icon: filesTabIcon,
       order: 10,
       hidden: false,
       dedupeKey: (tab) => tab.path,
@@ -148,7 +151,8 @@ export function builtinTabs(ctx: Context, options: BuiltinTabOptions = {}): read
       // log, and the git status needs a fetch — both stay out of the badge).
       id: 'git',
       title: () => t('changes'),
-      icon: (size: number) => <IconDiffOutline16 size={size} />,
+      description: () => t('guideDescGit'),
+      icon: changesTabIcon,
       order: 20,
       single: true,
       badge: (_ctx, scope) => {
@@ -170,7 +174,8 @@ export function builtinTabs(ctx: Context, options: BuiltinTabOptions = {}): read
     {
       id: 'subagent',
       title: () => t('subagent'),
-      icon: (size: number) => <IconThinkOutline16 size={size} />,
+      description: () => t('guideDescSubagent'),
+      icon: tasksTabIcon,
       order: 30,
       single: true,
       // Declarative settings: the auto-open switches render under this row in
@@ -198,7 +203,8 @@ export function builtinTabs(ctx: Context, options: BuiltinTabOptions = {}): read
     {
       id: 'sidechat',
       title: () => t('sideChat'),
-      icon: (size: number) => <IconNewChatOutline16 size={size} />,
+      description: () => t('guideDescSidechat'),
+      icon: sidechatTabIcon,
       order: 35,
       // Codex-style: EVERY side conversation is its own tab. A plain open
       // mints a fresh tab flagged `autoCreate` (the view creates the EMPTY
@@ -243,7 +249,8 @@ export function builtinTabs(ctx: Context, options: BuiltinTabOptions = {}): read
     {
       id: 'terminal',
       title: () => t('terminal'),
-      icon: (size: number) => <IconTerminalOutline16 size={size} />,
+      description: () => t('guideDescTerminal'),
+      icon: terminalTabIcon,
       order: 40,
       available: (_ctx, _scope, state) => uiTerminalCount(state) < TERMINAL_LIMIT,
       // Declarative settings: the model-facing terminal tools switch, the
@@ -307,7 +314,8 @@ export function builtinTabs(ctx: Context, options: BuiltinTabOptions = {}): read
     {
       id: 'browser',
       title: () => t('browser'),
-      icon: (size: number) => <IconGlobeOutline16 size={size} />,
+      description: () => t('guideDescBrowser'),
+      icon: browserTabIcon,
       order: 50,
       // Declarative settings: the sandbox escape hatch, the link-takeover
       // MASTER switch, and the per-protocol takeover switches (http on /
@@ -351,7 +359,7 @@ export function builtinTabs(ctx: Context, options: BuiltinTabOptions = {}): read
     {
       id: 'diff',
       title: () => t('changes'),
-      icon: (size: number) => <IconDiffOutline16 size={size} />,
+      icon: changesTabIcon,
       order: -1,
       hidden: true,
       dedupeKey: (tab) => tab.id,

src/client/changes/DiffPane.tsx

@@ -15,7 +15,7 @@ import { api, htmlUrl } from '../api.ts'
 import { t } from '../locales.ts'
 import { baseName } from '../paths.ts'
 import { resolveSidebarPath } from '../produced-files.ts'
-import { HTML_IFRAME_SANDBOX } from '../html-preview.ts'
+import { HtmlPreviewFrame } from '../HtmlPreviewFrame.tsx'
 import type { SidebarDiffRef, SidebarTab } from '../state.ts'
 import { DiffRows, ReadRows } from '../diff/DiffRows.tsx'
 import { PdfView } from '../PdfView.tsx'
@@ -66,19 +66,18 @@ function diffOf(op: FileOp, prior: string | undefined): readonly DiffRow[] {
   return []
 }
 
-/** The render view of one html op target: the route-src iframe. Extracted
- *  (and exported) so the always-sandboxed contract is pinned directly by the
- *  sandbox spec — this surface has NO no-sandbox escape hatch. */
+/** The render view of one html op target. Extracted (and exported) so the
+ *  always-sandboxed contract is pinned directly by the sandbox spec — this
+ *  surface has NO no-sandbox escape hatch, so it always takes the srcdoc
+ *  delivery path. */
 export function HtmlRenderPreview(props: { src: string; title: string }) {
   return (
     <div className={css.htmlPane}>
-      <iframe
+      <HtmlPreviewFrame
         className={css.htmlFrame}
+        url={props.src}
+        sandboxed
         title={props.title}
-        src={props.src}
-        sandbox={HTML_IFRAME_SANDBOX}
-        referrerPolicy="no-referrer"
-        allow=""
       />
     </div>
   )

src/client/chunk-loader.ts

@@ -153,7 +153,7 @@ const defaultScriptLoader: ChunkScriptLoader = (src) => new Promise((resolve, re
   }, { once: true })
   el.addEventListener('error', () => {
     el.remove()
-    reject(new Error(`[dsh-better-sidebar] chunk script ${src} failed to load`))
+    reject(new Error(`[dsh-apes-sidebar] chunk script ${src} failed to load`))
   }, { once: true })
   document.head.append(el)
 })
@@ -191,7 +191,7 @@ async function buildExternalsRequire(modules: ChunkModuleSystem): Promise<(spec:
     if (!table.has(spec)) {
       // Single quotes: the bundle-consistency scan regexes for require("...")
       // lexical calls — a double-quoted literal here would trip it.
-      throw new Error(`[dsh-better-sidebar] chunk require('${spec}') missed the module table`)
+      throw new Error(`[dsh-apes-sidebar] chunk require('${spec}') missed the module table`)
     }
     return table.get(spec)
   }
@@ -248,12 +248,12 @@ export async function loadChunk(name: ChunkName): Promise<ChunkExports> {
     if (test !== undefined) return test()
     const modules = moduleSystem()
     if (modules === undefined) {
-      throw new Error(`[dsh-better-sidebar] chunk "${name}": client module system unavailable`)
+      throw new Error(`[dsh-apes-sidebar] chunk "${name}": client module system unavailable`)
     }
     await scriptLoader(CHUNK_URL(name))
     const factory = chunkRegistry()[name]
     if (typeof factory !== 'function') {
-      throw new Error(`[dsh-better-sidebar] chunk "${name}" script did not register its factory`)
+      throw new Error(`[dsh-apes-sidebar] chunk "${name}" script did not register its factory`)
     }
     const require = await buildExternalsRequire(modules)
     const exports = factory(require)

src/client/chunks/editor.tsx

@@ -1,7 +1,7 @@
 /**
  * Lazy chunk entry: the code/markdown/html text editor (CodeMirror 6 + the
  * language packages). Built as `lib/client-editor.js` and registered under
- * `dsh-better-sidebar/editor` — fetched only when a text file is first
+ * `dsh-apes-sidebar/editor` — fetched only when a text file is first
  * opened (see chunk-loader.ts and docs/plans/2026-08-12-lazy-chunks-design.md).
  * Never import this module from the core bundle: it pulls CodeMirror into
  * the startup path.

src/client/chunks/terminal.tsx

@@ -1,7 +1,7 @@
 /**
  * Lazy chunk entry: the interactive terminal (xterm + fit addon). Built as
  * `lib/client-terminal.js` and registered under
- * `dsh-better-sidebar/terminal` — fetched only when a terminal tab is first
+ * `dsh-apes-sidebar/terminal` — fetched only when a terminal tab is first
  * opened (see chunk-loader.ts and docs/plans/2026-08-12-lazy-chunks-design.md).
  * Never import this module from the core bundle: it pulls xterm (and its
  * stylesheet) into the startup path.

src/client/conversation-draft.ts

@@ -170,12 +170,12 @@ export function appendToDraft(ctx: Context, sessionId: string, text: string): bo
   try {
     const actx = ctx.sessions.scope(sessionId)
     if (actx === undefined) {
-      console.warn('[dsh-better-sidebar] draft insert skipped: no session scope', sessionId)
+      console.warn('[dsh-apes-sidebar] draft insert skipped: no session scope', sessionId)
       return false
     }
     const conversation = ctx.get('conversation') as SidebarConversation | undefined
     if (conversation === undefined) {
-      console.warn('[dsh-better-sidebar] draft insert skipped: conversation service unavailable')
+      console.warn('[dsh-apes-sidebar] draft insert skipped: conversation service unavailable')
       return false
     }
     const input = conversation.input.for(actx)
@@ -189,7 +189,7 @@ export function appendToDraft(ctx: Context, sessionId: string, text: string): bo
     placeComposerCaretAfterInsert(next, caretAfter)
     return true
   } catch (error) {
-    console.warn('[dsh-better-sidebar] draft insert failed:', error)
+    console.warn('[dsh-apes-sidebar] draft insert failed:', error)
     return false
   }
 }
@@ -250,7 +250,7 @@ export function insertFileReference(ctx: Context, sessionId: string, relativePat
     const after = input.state.getSnapshot()
     return after.draftRev !== before.draftRev
   } catch (error) {
-    console.warn('[dsh-better-sidebar] file-reference insert failed:', error)
+    console.warn('[dsh-apes-sidebar] file-reference insert failed:', error)
     return false
   }
 }

src/client/desktop-env.ts

@@ -70,3 +70,24 @@ function parseTitlebarInset(raw: string | null): number {
 export function resetDesktopEnvForTests(): void {
   cached = undefined
 }
+
+/**
+ * The element the sidebar's panel host belongs in.
+ *
+ * The desktop shell stamps the upstream `#root` with
+ * `data-dsh-desktop-content-viewport` and gives it `isolation: isolate` — a
+ * stacking context around the whole app INCLUDING the shell's own overlay
+ * layer (`.dshDesktopOverlay`, z-index 1000), which is where a plugin's modal
+ * renders (the community market's, for one). A host parented to
+ * `document.body` sits OUTSIDE that context, so the panel layer's documented
+ * 25 outranks everything inside it and covered host modals; inside the
+ * viewport the same 25 keeps its meaning — above the app frame (z-index auto)
+ * and below the overlay layer (1000).
+ *
+ * Every other deployment (plain web, an unframed shell) keeps the body mount.
+ * @param doc - the document to resolve against.
+ * @returns the content viewport when the shell framed one, else the body.
+ */
+export function panelHostParent(doc: Document = document): HTMLElement {
+  return doc.querySelector<HTMLElement>('#root[data-dsh-desktop-content-viewport]') ?? doc.body
+}

src/client/file-icons.tsx

@@ -0,0 +1,62 @@
+/**
+ * Built-in file and folder glyphs for the file tree (feature: file icons).
+ *
+ * The built-in set is DSH's OWN file-type artwork: `FileTypeIcon` from
+ * `@deepseek-ai/dsh-client-ui-primitives` classifies a path and renders the
+ * same glyphs the host's own explorer shows — the 48 full-color code and
+ * configuration categories, plus the category-colored sheet glyphs for
+ * markdown, images, PDFs, office documents, video, folders and the generic
+ * fallback. Colored artwork is content, not chrome, and the host draws it
+ * with its own palette, so this module carries no color literals and stays
+ * inside the skin contract (the guide's §12).
+ *
+ * Nothing here needs a lazy chunk: the artwork belongs to a platform module
+ * the client already holds in its frozen module table, so the core bundle
+ * gains a function call rather than 500-odd icon rules.
+ *
+ * External plugins that want their own glyphs (per extension, per exact file
+ * name, per directory name) register `FileIconDescriptor`s through
+ * `ctx.betterSidebar.registerFileIcon`; their registrations win over these.
+ */
+import type { ReactNode } from 'react'
+import { FileTypeIcon } from '@deepseek-ai/dsh-client-ui-primitives'
+
+/**
+ * A file row: the host's own classifier and artwork for any path. Unknown
+ * extensions land on the generic document glyph, exactly like the host's
+ * explorer.
+ * @param path - the row's path (any separator; the classifier reads the basename).
+ * @param size - the square edge in px.
+ * @returns the host's file-type glyph.
+ */
+export function builtinFileIcon(path: string, size: number): ReactNode {
+  return <FileTypeIcon path={path} size={size} />
+}
+
+/**
+ * A directory row: the host's folder glyph.
+ *
+ * The host ships ONE folder drawing (`kind: 'folder'` resolves to its
+ * monochrome `IconFolderClose16`, which rides `currentColor` and therefore
+ * still follows the skin), and the classifier never returns a folder kind of
+ * its own. The expansion state is already legible from the tree's own chevron
+ * and row affordances, so this deliberately does not invent a second folder
+ * drawing.
+ * @param _open - whether the row is expanded (accepted for API compatibility).
+ * @param size - the square edge in px.
+ * @returns the host's folder glyph.
+ */
+export function builtinFolderIcon(_open: boolean, size: number): ReactNode {
+  return <FileTypeIcon kind="folder" size={size} />
+}
+
+/**
+ * The last-resort glyph: the host's generic document, for the resolver's leaf
+ * when no registration and no built-in match applies (and for surfaces that
+ * render a file row without a service).
+ * @param size - the square edge in px.
+ * @returns the host's generic file glyph.
+ */
+export function fallbackFileIcon(size: number): ReactNode {
+  return <FileTypeIcon kind="other" size={size} />
+}

src/client/html-preview.ts

@@ -1,7 +1,8 @@
 /**
  * Shared vocabulary of the sidebar's HTML preview surfaces (the editor's
  * html viewer and the changes tab's op render preview): the sandbox tokens
- * both preview iframes load with.
+ * both preview iframes load with, plus the document-base rewrite the srcdoc
+ * delivery path needs.
  */
 
 /**
@@ -13,3 +14,47 @@
  * render preview always stays sandboxed.
  */
 export const HTML_IFRAME_SANDBOX = 'allow-scripts allow-popups allow-downloads allow-modals'
+
+/** Whether a document already declares its own base URL. */
+const HAS_BASE = /<base[\s/>]/i
+
+/** Index just past the element a `<base>` must precede to land in <head>. */
+function insertionPoint(html: string): number {
+  const head = /<head\b[^>]*>/i.exec(html)
+  if (head !== null) return head.index + head[0].length
+  const htmlTag = /<html\b[^>]*>/i.exec(html)
+  if (htmlTag !== null) return htmlTag.index + htmlTag[0].length
+  return 0
+}
+
+/**
+ * The directory part of a preview route URL, with its trailing slash.
+ * @param url - the `/sidebar/html/<sessionId>/<path…>` route URL.
+ * @returns the URL up to and including the last `/`.
+ */
+export function previewBaseOf(url: string): string {
+  const cut = url.lastIndexOf('/')
+  return cut < 0 ? url : url.slice(0, cut + 1)
+}
+
+/**
+ * Point a preview document's relative references back at its own route.
+ *
+ * A `srcdoc` document has no URL of its own — the browser resolves its
+ * relative references against the EMBEDDING page's URL, so `./style.css` in a
+ * previewed file would resolve to the GUI's origin and hit whatever route
+ * happens to match. Injecting `<base href="<the file's route directory>">`
+ * keeps relative resolution inside `/sidebar/html/…`, where the file's own
+ * siblings live. A document that declares its own `<base>` is left alone: the
+ * author said what the base is.
+ *
+ * @param html - the previewed document's markup.
+ * @param url - the route URL the document was fetched from.
+ * @returns the markup, with a base element injected when it had none.
+ */
+export function withPreviewBase(html: string, url: string): string {
+  if (HAS_BASE.test(html)) return html
+  const href = previewBaseOf(url).replace(/"/g, '&quot;')
+  const at = insertionPoint(html)
+  return `${html.slice(0, at)}<base href="${href}">${html.slice(at)}`
+}

src/client/index.tsx

@@ -1,5 +1,5 @@
 /**
- * Client half of dsh-better-sidebar: resolves the user's "Side card"
+ * Client half of dsh-apes-sidebar: resolves the user's "Side card"
  * preferences through the plugin's own fenced settings route, mounts the
  * right sidebar portal (inside an error boundary so a rendering failure
  * shows an error strip instead of a blank panel), registers the turn-tail
@@ -15,6 +15,7 @@ import { allLeaves, createSidebarStore, isAgentTabId } from './state.ts'
 import { createBetterSidebarService, matchUrlTarget } from './service.ts'
 import { revalidateChunksOnReactivate, setChunkModuleSystem } from './chunk-loader.ts'
 import { registerBuiltins } from './builtins/index.ts'
+import { registerApesTabs, APES_LOCALE_NS, apesZh, apesEn, attachApesLocale } from './apes/index.ts'
 import { Sidebar } from './Sidebar.tsx'
 import { RenderBoundary } from './RenderBoundary.tsx'
 import { registerTurnTailInterception } from './intercept.tsx'
@@ -26,6 +27,7 @@ import { registerLinkInterception } from './link-intercept.ts'
 import { registerImeGuard } from './ime-guard.ts'
 import { registerSettingsNavIcon } from './settings-nav-icon.ts'
 import { loadBootDecision } from './prefs.ts'
+import { panelHostParent } from './desktop-env.ts'
 import { SideCardSection } from './SideCardSection.tsx'
 import { api } from './api.ts'
 import { LOCALE_NS, attachLocale, attachBetterLocale, t, zh, en } from './locales.ts'
@@ -61,11 +63,17 @@ export function apply(ctx: Context): void {
   // plugin's dictionaries into the shared locale registry. The disposers
   // run on fiber disposal, so re-activation (HMR) re-registers cleanly.
   attachLocale(ctx.locale)
+  // The apes module has its own locale namespace (isolated from the upstream
+  // betterSidebar dicts): attach it so apes t() tracks the DSH active-locale
+  // preference, and register its zh/en dicts under `apes`.
+  attachApesLocale(ctx.locale)
   ctx.effect(() => {
     const offZh = ctx.locale.register(LOCALE_NS, 'zh', zh)
     const offEn = ctx.locale.register(LOCALE_NS, 'en', en)
-    return () => { offZh(); offEn() }
-  }, 'dsh-better-sidebar: dictionaries')
+    const offApesZh = ctx.locale.register(APES_LOCALE_NS, 'zh', apesZh as Record<string, string>)
+    const offApesEn = ctx.locale.register(APES_LOCALE_NS, 'en', apesEn as Record<string, string>)
+    return () => { offZh(); offEn(); offApesZh(); offApesEn() }
+  }, 'dsh-apes-sidebar: dictionaries')
 
   // Opt-in third-language support through @huanlin/dsh-plugin-better-locale.
   // When that plugin is installed, it publishes `ctx.betterLocale` (the
@@ -129,7 +137,7 @@ export function apply(ctx: Context): void {
       dispose?.()
       attachBetterLocale(undefined)
     }
-  }, 'dsh-better-sidebar: better-locale lazy integration')
+  }, 'dsh-apes-sidebar: better-locale lazy integration')
   // One store instance per activation: production code creates it only here,
   // then hands it to the mounted panel and closes over it in the slot
   // registrations (the official createXXXStore() factory rule — no
@@ -150,17 +158,17 @@ export function apply(ctx: Context): void {
   service.setSurface(nativeSurface)
   ctx.effect(
     () => registerNativeSurface({ ctx, store: sidebarStore, service, records: nativeRecords }),
-    'dsh-better-sidebar: native right-Sidebar registrations',
+    'dsh-apes-sidebar: native right-Sidebar registrations',
   )
   // The bottom workbench's expand/collapse button in DSH's session header
   // (the header's corner seat belongs to the native sidebar's own control).
   ctx.effect(
     () => registerBottomToggle(ctx, sidebarStore),
-    'dsh-better-sidebar: bottom-workbench toggle',
+    'dsh-apes-sidebar: bottom-workbench toggle',
   )
   ctx.effect(
     () => () => { nativeSurface.dispose(); service.setSurface(undefined) },
-    'dsh-better-sidebar: native right-Sidebar surface',
+    'dsh-apes-sidebar: native right-Sidebar surface',
   )
   // Terminal tab titles use the host's effective shell name (e.g. bash/zsh)
   // instead of "Terminal 1". Start with a safe fallback and replace it as
@@ -186,7 +194,17 @@ export function apply(ctx: Context): void {
   // fiber disposal (HMR-safe).
   ctx.effect(
     () => registerBuiltins(ctx, service, { terminalTitle: () => terminalTitle }),
-    'dsh-better-sidebar: register built-in tabs and viewers',
+    'dsh-apes-sidebar: register built-in tabs and viewers',
+  )
+  // The apes:* information-layer tabs (the fork's own contribution, isolated
+  // under src/client/apes). Registered through the SAME service as the
+  // builtins, so the fork's native adapter (`native/index.ts`) turns each one
+  // into an official right-sidebar tab type + body automatically — that is the
+  // entire reason this fork now runs ONE sidebar instead of two. The disposer
+  // runs on fiber disposal (HMR-safe).
+  ctx.effect(
+    () => registerApesTabs(ctx, service),
+    'dsh-apes-sidebar: register apes tabs',
   )
   // A failure anywhere in the client lifecycle must never take the app down
   // silently: log with the plugin prefix and pin a visible diagnostic strip
@@ -197,7 +215,7 @@ export function apply(ctx: Context): void {
   // byte-identical to the old hardcoded bar, and any `--dsw-alias-*` skin
   // re-themes it (guide §12: no hardcoded colors).
   const fail = (phase: string, error: unknown): void => {
-    console.error(`[dsh-better-sidebar] ${phase} error:`, error)
+    console.error(`[dsh-apes-sidebar] ${phase} error:`, error)
     try {
       const bar = document.createElement('div')
       bar.style.cssText = 'position:fixed;left:8px;bottom:8px;z-index:2147483000;max-width:70vw;padding:8px 12px;'
@@ -205,7 +223,7 @@ export function apply(ctx: Context): void {
         + 'color:var(--dsw-alias-state-error-primary,#f2a1a1);'
         + 'background:var(--dsw-alias-bg-layer-3,var(--dsw-alias-bg-base,#1b1b22));'
         + 'border:1px solid var(--dsw-alias-state-error-primary,#f2a1a1);border-radius:8px;white-space:pre-wrap'
-      bar.textContent = `[dsh-better-sidebar] ${phase} error: ${error instanceof Error ? error.message : String(error)}`
+      bar.textContent = `[dsh-apes-sidebar] ${phase} error: ${error instanceof Error ? error.message : String(error)}`
       document.body.appendChild(bar)
     } catch {
       // Nothing left to report with.
@@ -242,17 +260,26 @@ export function apply(ctx: Context): void {
         host?.remove()
         host = undefined
       }
-      /** Re-attach the host if the page (a desktop shell wrapper, SPA
-       *  navigation, …) ever removes it from <body>. Cheap: childList only,
-       *  no subtree, no attribute filtering. */
+      /** Put the host in the layer it belongs to — re-attaching it if the
+       *  page (a desktop shell wrapper, SPA navigation, …) removed it, and
+       *  moving it if the shell framed the content viewport after our mount
+       *  (see panelHostParent). */
+      const anchorHost = (): void => {
+        if (host === undefined) return
+        const parent = panelHostParent()
+        if (host.parentElement !== parent) parent.appendChild(host)
+      }
+      /** Watch for the host being removed, and for the shell stamping its
+       *  framed mode onto <body> (the same effect tags #root as the content
+       *  viewport, which is where the host must live). */
       const guardAnchor = (): void => {
         if (bodyObserver !== undefined) return
-        bodyObserver = new MutationObserver(() => {
-          if (host !== undefined && !document.body.contains(host)) {
-            document.body.appendChild(host)
-          }
+        bodyObserver = new MutationObserver(anchorHost)
+        bodyObserver.observe(document.body, {
+          childList: true,
+          attributes: true,
+          attributeFilter: ['data-dsh-desktop-mode'],
         })
-        bodyObserver.observe(document.body, { childList: true })
       }
       /** One-shot geometry self-check: if the host page transforms
        *  <html>/<body> itself (exotic shells), a fixed panel host would
@@ -274,7 +301,7 @@ export function apply(ctx: Context): void {
             return
           }
           layer.setAttribute('data-dsh-panel-host-degraded', '')
-          console.warn('[dsh-better-sidebar] panel host geometry mismatch — a page-level transform was detected; using degraded viewport sync')
+          console.warn('[dsh-apes-sidebar] panel host geometry mismatch — a page-level transform was detected; using degraded viewport sync')
           // Track our own compensating translation so the loop judges the
           // UNCORRECTED geometry: clearing degraded mode must wait for the
           // ancestor transform to actually disappear — the frame right after
@@ -305,8 +332,11 @@ export function apply(ctx: Context): void {
         if (mounted || disposed) return
         try {
           host = document.createElement('div')
-          host.setAttribute('data-dsh-better-sidebar', '')
-          document.body.appendChild(host)
+          host.setAttribute('data-dsh-apes-sidebar', '')
+          // The shell's framed content viewport when there is one (see
+          // panelHostParent): it is a stacking context, so a body-level host
+          // would paint above every overlay the shell hosts inside it.
+          panelHostParent().appendChild(host)
           root = createRoot(host)
           root.render(createElement(RenderBoundary, { className: css.boundaryError }, createElement(Sidebar, { ctx, store: sidebarStore })))
           mounted = true
@@ -352,7 +382,7 @@ export function apply(ctx: Context): void {
         offRemote?.()
         unmount()
       }
-    }, 'dsh-better-sidebar: sidebar mount')
+    }, 'dsh-apes-sidebar: sidebar mount')
 
     ctx.effect(
       () => {
@@ -363,7 +393,7 @@ export function apply(ctx: Context): void {
           return () => {}
         }
       },
-      'dsh-better-sidebar: turn-tail interception',
+      'dsh-apes-sidebar: turn-tail interception',
     )
 
     ctx.effect(
@@ -407,7 +437,7 @@ export function apply(ctx: Context): void {
           return () => {}
         }
       },
-      'dsh-better-sidebar: link interception',
+      'dsh-apes-sidebar: link interception',
     )
 
     // The IME guard: composition keys (candidate arrows, confirm, cancel)
@@ -427,7 +457,7 @@ export function apply(ctx: Context): void {
           return () => {}
         }
       },
-      'dsh-better-sidebar: IME composition guard',
+      'dsh-apes-sidebar: IME composition guard',
     )
 
     // DSH 0.1.x does not yet carry an icon through the settings.section
@@ -437,7 +467,7 @@ export function apply(ctx: Context): void {
     // the marker for HMR / plugin disable.
     ctx.effect(
       () => registerSettingsNavIcon(() => t('settingsNav')),
-      'dsh-better-sidebar: settings navigation icon',
+      'dsh-apes-sidebar: settings navigation icon',
     )
 
     // The "Side card" settings section: appears in the DSH Settings shell

src/client/intercept.tsx

@@ -112,6 +112,7 @@ export function SidebarProducedFiles(props: {
 export function registerTurnTailInterception(ctx: Context, store: SidebarStore): () => void {
   return ctx.slots.inject('conversation.chat.turnTail', () => ctx.slots.register({
     name: 'conversation.chat.turnTail',
+    id: 'dsh-apes-sidebar:turn-tail',
     // Decline the takeover while the editor tab type is disabled in the side
     // card settings: the produced-files row falls back to the default
     // deliverables behavior instead of offering chips that cannot open. Also
@@ -122,7 +123,7 @@ export function registerTurnTailInterception(ctx: Context, store: SidebarStore):
       return selectProducedFiles(owner)
     },
     priority: -1,
-    registrant: 'dsh-better-sidebar',
+    registrant: 'dsh-apes-sidebar',
     inject: (sessionId: string) => ({
       openInSidebar: (path: string) => { openSidebarFile(ctx, store, sessionId, path) },
       onShowInFolder: (files: readonly string[]) => { revealInExplorer(ctx, store, sessionId, files) },

src/client/lang.ts

@@ -217,7 +217,7 @@ export function languageForPath(path: string): Language | LanguageSupport | null
     return FACTORIES[key]!()
   } catch (error) {
     // A broken factory degrades to plain text, never crashes the editor.
-    console.warn(`[dsh-better-sidebar] language factory "${key}" failed:`, error)
+    console.warn(`[dsh-apes-sidebar] language factory "${key}" failed:`, error)
     return null
   }
 }

src/client/layout.css

@@ -60,11 +60,11 @@ body[data-dsh-sidebar-dragging] #root [data-dsh-center-col] {
    only this plugin's localized row; render the requested Lucide
    gallery-horizontal-end SVG as a currentColor mask so it follows the native
    nav hover/active colors without changing the shell's 16px icon rhythm. */
-[data-dsh-better-sidebar-settings-nav] > svg:first-child {
+[data-dsh-apes-sidebar-settings-nav] > svg:first-child {
   display: none;
 }
 
-[data-dsh-better-sidebar-settings-nav]::before {
+[data-dsh-apes-sidebar-settings-nav]::before {
   content: '';
   flex: none;
   width: 16px;

src/client/lazy-chunk.tsx

@@ -37,7 +37,7 @@ function LazyChunkView<P extends object>({ chunk, pick, props }: LazyChunkViewPr
       if (cancelled) return
       const Comp = pick(mod)
       if (Comp === undefined) {
-        setState({ status: 'error', message: `[dsh-better-sidebar] chunk "${chunk}" is missing its component` })
+        setState({ status: 'error', message: `[dsh-apes-sidebar] chunk "${chunk}" is missing its component` })
         return
       }
       setState({ status: 'ready', Comp })

src/client/locales-ar.ts

@@ -18,6 +18,12 @@
 /** The ar dictionary (key-set-equal to zh, enforced by the type annotation in locales.ts). */
 export const ar: Record<string, string> = {
   files: 'الملفات',
+  guideDescFiles: 'استعرض شجرة ملفات مساحة العمل؛ انقر للمعاينة أو التحرير',
+  guideDescGit: 'تغييرات Git وتعديلات ملفات هذه الجلسة في تبويب واحد',
+  guideDescSubagent: 'بنية الوكلاء الفرعيين والمهام الخلفية مباشرةً',
+  guideDescSidechat: 'خيط متابعة مستقل يرث سياق هذه الجلسة',
+  guideDescTerminal: 'صدفة حقيقية (xterm + pty) مع إعادة الاتصال',
+  guideDescBrowser: 'متصفح مدمج يمكنه فتح روابط المحادثة',
   changesSessionEmpty: 'لا توجد عمليات ملفات في هذه الجلسة بعد',
   changesRead: 'قراءة',
   changesMdReading: 'قراءة',
@@ -101,6 +107,8 @@ export const ar: Record<string, string> = {
   terminalError: 'فشل اتصال الطرفية',
   terminalConnectFailed: 'فشل اتصال الطرفية عدة مرات',
   terminalRetry: 'إعادة المحاولة',
+  terminalWaitBanner: 'الوكيل ينتظر {needle}',
+  terminalSkipWait: 'تخطي الانتظار',
   terminalDepsFailed: 'فشل تحميل تبعية الطرفية node-pty',
   terminalDepsHint: 'شغّل الأمر التالي في طرفية أو cmd على جهاز DSH للإصلاح، ثم أعد المحاولة (يبقى node-pty متزامناً مع إصدار نواة DSH):',
   terminalDepsProfile: ' (الملف الشخصي المكتشف: {profile})',
@@ -396,7 +404,7 @@ export const ar: Record<string, string> = {
   addPluginsViewerCardDesc: 'تسجيل معاينة نوع ملف',
   addPluginsTabDesc: 'يمكن توسيع صفحات الشريط الجانبي (التبويبات) بواسطة الإضافات. تُسجَّل الإضافات عبر خدمة ctx.betterSidebar؛ النقر على «تثبيت» ينسخ أمر التثبيت — الصقه في طرفية حيث يقيم ملف DSH الشخصي وشغّله.',
   addPluginsViewerDesc: 'يمكن توسيع عارضات الملفات بواسطة الإضافات. تُسجَّل الإضافات عبر خدمة ctx.betterSidebar؛ النقر على «تثبيت» ينسخ أمر التثبيت — الصقه في طرفية حيث يقيم ملف DSH الشخصي وشغّله.',
-  addPluginsBrowseMore: 'تصفّح المزيد من الإضافات على GitHub (topic: dsh-better-sidebar)',
+  addPluginsBrowseMore: 'تصفّح المزيد من الإضافات على GitHub (topic: dsh-apes-sidebar)',
   addPluginsSearch: 'البحث باسم الإضافة / الوصف…',
   addPluginsNoMatch: 'لا إضافات مطابقة',
   addPluginsRecommended: 'إضافات موصى بها',
@@ -409,7 +417,7 @@ export const ar: Record<string, string> = {
   pluginGithubWorkbenchDesc: 'تبويب GitHub Workbench: شجرة المستودع البعيد + Issues / Pull requests / Actions مع دعم كامل للكتابة — إنشاء Issue/PR، والتعليق، والتعديل، والإغلاق/إعادة الفتح، والدمج عبر squash·merge·rebase (بتأكيد قوي)، وإعادة تشغيل CI أو إلغائها؛ يعرض مبدّل المستودعات تلقائيًا المستودعات المتاحة ويتيح البحث في المستودعات العامة؛ وبدون better-sidebar يتحول تلقائيًا إلى لوحة جانبية مستقلة على اليمين',
   pluginMdExportDesc: 'يضيف زر «تصدير» إلى شريط أدوات Markdown في better-sidebar: يعرض ملف .md الحالي بنقرة واحدة كملف HTML مستقل (الجداول/كتل الأكواد/مخططات Mermaid مدمجة، والتخطيط يتبع سمة المعاينة) ويحفظه بجوار الملف، أو يصدّره PDF عبر نافذة الطباعة',
   pluginCodeNavDesc: 'تنقل معاينة الكود: يكتشف اللغة تلقائياً من نوع الملف ويبرز الصياغة، مخطط الرموز (تصفية الفئات/الطرق/المتغيرات + قفزة بنقرة واحدة)، والبحث داخل الملف (إبراز كل التطابقات، السابق/التالي، مطابقة حالة الأحرف) — يتولى معاينة ملفات الكود في محرر better-sidebar',
-  pluginSuhuangScrollDesc: 'يربط بيئة Suhuang Scroll المحلية بإعدادات DSH وbetter-sidebar لإعداد النموذج واختبار الاتصال والتحكم في التصحيح المتواصل؛ يتطلب Suhuang Scroll Runtime وdsh-better-sidebar',
+  pluginSuhuangScrollDesc: 'يربط بيئة Suhuang Scroll المحلية بإعدادات DSH وbetter-sidebar لإعداد النموذج واختبار الاتصال والتحكم في التصحيح المتواصل؛ يتطلب Suhuang Scroll Runtime وdsh-apes-sidebar',
   pluginBetterOverleafDesc: 'تبويب Overleaf لـ better-sidebar: تسجيل دخول مباشر عبر متصفح CDP (يدعم Chromium من جهات أخرى)، قائمة المشاريع/التبديل، نسخ git محلية ضمن <workspace>/overleaf/، مزامنة git ثنائية الاتجاه مع تراجع إلى API للقراءة فقط، ومعاينة الملفات عبر مساحة عمل الشريط الجانبي',
   pluginGitRemotesDesc: 'تبويب Git Remotes: فرع/أصل/أمام-خلف، fetch (مع prune اختياري)، ff-only pull، والدفع فقط بعد تأكيد داخل التبويب. لا يستبدل تبويب Git المدمج للإدراج/التثبيت، ولا يقدّم force-push أو أداة دفع آلي للنموذج',
   pluginSentinelDesc: 'نظام إيقاظ وكيل يحرّكه تحقّق الشروط: مستشعرات ملف/عملية/منفذ/HTTP/أمر/webhook توقظ الجلسات الخاملة عند تحقّق الشرط؛ يُسجِّل تبويب «Sentinel» مع جدول مراقبة شامل للخادم',

src/client/locales-de.ts

@@ -3,6 +3,12 @@
  */
 export const de: Record<string, string> = {
   files: 'Dateien',
+  guideDescFiles: 'Dateibaum des Arbeitsbereichs durchsuchen; Klick öffnet Vorschau oder Editor',
+  guideDescGit: 'Git-Änderungen und Dateiänderungen dieser Sitzung in einem Tab',
+  guideDescSubagent: 'Subagent-Topologie und Hintergrundaufgaben, live',
+  guideDescSidechat: 'Ein unabhängiger Folge-Thread mit dem Kontext dieser Sitzung',
+  guideDescTerminal: 'Eine echte Shell (xterm + pty) mit Wiederverbindung',
+  guideDescBrowser: 'Eingebetteter Browser, der Chat-Links übernehmen kann',
   changesSessionEmpty: 'Noch keine Dateioperationen in dieser Sitzung',
   changesRead: 'Lesen',
   changesMdReading: 'Lesen',
@@ -86,6 +92,8 @@ export const de: Record<string, string> = {
   terminalError: 'Terminalverbindung fehlgeschlagen',
   terminalConnectFailed: 'Terminal konnte wiederholt keine Verbindung herstellen',
   terminalRetry: 'Erneut versuchen',
+  terminalWaitBanner: 'Agent wartet auf {needle}',
+  terminalSkipWait: 'Warten überspringen',
   terminalDepsFailed: 'Die Terminal-Abhängigkeit node-pty konnte nicht geladen werden',
   terminalDepsHint: 'Führen Sie den folgenden Befehl in einem Terminal oder in cmd auf dem DSH-System aus, um dies zu beheben, und klicken Sie dann auf „Erneut versuchen“ (node-pty bleibt mit der DSH-Core-Version synchron):',
   terminalDepsProfile: ' (erkanntes Profil: {profile})',
@@ -381,7 +389,7 @@ export const de: Record<string, string> = {
   addPluginsViewerCardDesc: 'Eine Dateityp-Vorschau registrieren',
   addPluginsTabDesc: 'Seitenleisten-Seiten (Tabs) können durch Plugins erweitert werden. Plugins registrieren sich über den ctx.betterSidebar-Dienst; ein Klick auf „Installieren“ kopiert den Installationsbefehl – fügen Sie ihn in einem Terminal ein, in dem Ihr DSH-Profil liegt, und führen Sie ihn aus.',
   addPluginsViewerDesc: 'Datei-Viewer können durch Plugins erweitert werden. Plugins registrieren sich über den ctx.betterSidebar-Dienst; ein Klick auf „Installieren“ kopiert den Installationsbefehl – fügen Sie ihn in einem Terminal ein, in dem Ihr DSH-Profil liegt, und führen Sie ihn aus.',
-  addPluginsBrowseMore: 'Weitere Plugins auf GitHub durchsuchen (Topic: dsh-better-sidebar)',
+  addPluginsBrowseMore: 'Weitere Plugins auf GitHub durchsuchen (Topic: dsh-apes-sidebar)',
   addPluginsSearch: 'Nach Plugin-Name oder -Beschreibung suchen…',
   addPluginsNoMatch: 'Keine passenden Plugins',
   addPluginsRecommended: 'Empfohlene Plugins',
@@ -394,7 +402,7 @@ export const de: Record<string, string> = {
   pluginGithubWorkbenchDesc: '„GitHub Workbench“-Tab: Repository-Baum + Issues / Pull requests / Actions mit vollen Schreibrechten — Issue/PR erstellen, kommentieren, bearbeiten, schließen/wieder öffnen, squash·merge·rebase-Merge (mit starker Bestätigung), CI erneut ausführen/abbrechen; der Repo-Umschalter listet automatisch zugreifbare Repos auf und durchsucht öffentliche; ohne better-sidebar fällt er auf ein eigenständiges rechtes Panel zurück',
   pluginMdExportDesc: 'Fügt einen „Export"-Button zur Markdown-Symbolleiste in better-sidebar hinzu: rendert die aktuelle .md per Klick in eigenständiges HTML (Tabellen/Codeblöcke/Mermaid-Diagramme inline, Layout folgt dem Vorschau-Theme) und speichert es neben der .md, oder exportiert über den Druckdialog als PDF',
   pluginCodeNavDesc: 'Code-Vorschau-Navigation: erkennt die Sprache am Dateityp und hebt die Syntax hervor, Symbol-Gliederung (Filter für Klassen/Methoden/Variablen + Sprung mit einem Klick) und Suche in der Datei (alle Treffer hervorgehoben, vor/zurück, Groß-/Kleinschreibung) — übernimmt die Code-Dateivorschau im better-sidebar-Editor',
-  pluginSuhuangScrollDesc: 'Verbindet die lokale Suhuang Scroll Runtime mit den DSH-Einstellungen und better-sidebar für Modellkonfiguration, Verbindungstests und fortlaufende Bewertung; benötigt Suhuang Scroll Runtime und dsh-better-sidebar',
+  pluginSuhuangScrollDesc: 'Verbindet die lokale Suhuang Scroll Runtime mit den DSH-Einstellungen und better-sidebar für Modellkonfiguration, Verbindungstests und fortlaufende Bewertung; benötigt Suhuang Scroll Runtime und dsh-apes-sidebar',
   pluginBetterOverleafDesc: 'Overleaf-Tab für better-sidebar: Login direkt über CDP-Browser (Chromium von Drittanbietern unterstützt), Projekliste/-wechsel, lokale git-Spiegel unter <workspace>/overleaf/, bidirektionaler git-Abgleich mit Read-only-API-Fallback und Dateivorschau über die Sidebar-Workbench',
   pluginGitRemotesDesc: '„Git-Remotes“-Tab: Branches/Upstream/ahead-behind ansehen, fetch (optional prune), ff-only pull und push erst nach Bestätigung im Tab. Ersetzt nicht den eingebauten Stagen/Commit-Tab und bietet weder force-push noch automatisches Push-Werkzeug für das Modell',
   pluginSentinelDesc: 'Bedingungsgesteuertes Wecksystem für Agenten: Datei-/Prozess-/Port-/HTTP-/Befehls-/Webhook-Sensoren wecken ruhende Sitzungen, wenn Bedingungen zutreffen; registriert einen „Sentinel“-Tab mit der serverweiten Überwachungstabelle',

src/client/locales-fr.ts

@@ -10,6 +10,12 @@
 /** fr dictionary for the `betterSidebar` namespace. */
 export const fr: Record<string, string> = {
   files: 'Fichiers',
+  guideDescFiles: 'Parcourir l\'arborescence du workspace ; un clic ouvre l\'aperçu ou l\'édition',
+  guideDescGit: 'Modifications Git et éditions de cette session dans un seul onglet',
+  guideDescSubagent: 'Topologie des sous-agents et tâches d\'arrière-plan, en direct',
+  guideDescSidechat: 'Un fil de suivi indépendant héritant du contexte de cette session',
+  guideDescTerminal: 'Un vrai shell (xterm + pty) avec reconnexion',
+  guideDescBrowser: 'Navigateur intégré, qui peut reprendre les liens du chat',
   changesSessionEmpty: 'Aucune opération de fichier dans cette session',
   changesRead: 'Lecture',
   changesMdReading: 'Lecture',
@@ -93,6 +99,8 @@ export const fr: Record<string, string> = {
   terminalError: 'Échec de la connexion au terminal',
   terminalConnectFailed: 'Le terminal a échoué à se connecter à plusieurs reprises',
   terminalRetry: 'Réessayer',
+  terminalWaitBanner: 'L’agent attend {needle}',
+  terminalSkipWait: 'Ignorer l’attente',
   terminalDepsFailed: 'Échec du chargement de la dépendance terminal node-pty',
   terminalDepsHint: 'Exécutez la commande suivante dans un terminal ou cmd de l’environnement DSH pour réparer, puis cliquez sur Réessayer (node-pty reste à la même version que le cœur DSH) :',
   terminalDepsProfile: ' (profil détecté : {profile})',
@@ -388,7 +396,7 @@ export const fr: Record<string, string> = {
   addPluginsViewerCardDesc: 'Enregistrer un aperçu d’un type de fichier',
   addPluginsTabDesc: 'Les pages de la barre latérale (onglets) peuvent être étendues par des plugins. Les plugins s’enregistrent via le service ctx.betterSidebar ; cliquez sur « Installer » pour copier la commande d’installation, collez-la dans un terminal de l’environnement DSH et exécutez-la.',
   addPluginsViewerDesc: 'Les aperçus de fichiers peuvent être étendus par des plugins. Les plugins s’enregistrent via le service ctx.betterSidebar ; cliquez sur « Installer » pour copier la commande d’installation, collez-la dans un terminal de l’environnement DSH et exécutez-la.',
-  addPluginsBrowseMore: 'Parcourir plus de plugins sur GitHub (topic : dsh-better-sidebar)',
+  addPluginsBrowseMore: 'Parcourir plus de plugins sur GitHub (topic : dsh-apes-sidebar)',
   addPluginsSearch: 'Rechercher par nom / description de plugin…',
   addPluginsNoMatch: 'Aucun plugin correspondant',
   addPluginsRecommended: 'Plugins recommandés',
@@ -401,7 +409,7 @@ export const fr: Record<string, string> = {
   pluginGithubWorkbenchDesc: 'Onglet « GitHub Workbench » de better-sidebar : arborescence du dépôt distant + Issues / Pull requests / Actions avec prise en charge complète en écriture — création d’issue/PR, commentaire, édition, fermeture/réouverture, merge squash·merge·rebase (confirmation renforcée), relance/annulation de la CI ; le sélecteur de dépôt liste automatiquement les dépôts accessibles et recherche les dépôts publics ; sans better-sidebar, il bascule sur un panneau latéral droit autonome',
   pluginMdExportDesc: 'Ajoute un bouton « Exporter » à la barre d’outils Markdown de better-sidebar : rend en un clic le .md courant en HTML autonome (tableaux/blocs de code/diagrammes Mermaid en ligne, mise en page fidèle au thème d’aperçu) et l’enregistre à côté du .md, ou exporte en PDF via la boîte de dialogue d’impression',
   pluginCodeNavDesc: 'Navigation de prévisualisation de code : détecte le langage selon le type de fichier et colore la syntaxe, plan des symboles (filtres classes/méthodes/variables + saut en un clic) et recherche dans le fichier (toutes les correspondances surlignées, précédent/suivant, respect de la casse) — prend en charge l’aperçu des fichiers de code dans l’éditeur better-sidebar',
-  pluginSuhuangScrollDesc: 'Connecte le Runtime Suhuang Scroll local aux réglages DSH et à better-sidebar pour configurer le modèle, tester la connexion et contrôler la correction continue ; nécessite Suhuang Scroll Runtime et dsh-better-sidebar',
+  pluginSuhuangScrollDesc: 'Connecte le Runtime Suhuang Scroll local aux réglages DSH et à better-sidebar pour configurer le modèle, tester la connexion et contrôler la correction continue ; nécessite Suhuang Scroll Runtime et dsh-apes-sidebar',
   pluginBetterOverleafDesc: 'Onglet Overleaf pour better-sidebar : connexion directe via navigateur CDP (Chromium tiers pris en charge), liste/sélection de projets, miroirs git locaux sous <workspace>/overleaf/, synchronisation git bidirectionnelle avec repli API en lecture seule, et aperçu des fichiers via l’atelier de la barre latérale',
   pluginGitRemotesDesc: 'Onglet Git Remotes de better-sidebar : branches/amonts/ahead-behind, fetch (avec prune possible), pull en ff-only, push seulement après confirmation. Ne remplace pas la mise en scène/les commits du Git intégré et ne fournit pas de force-push ni de push automatique par le modèle',
   pluginSentinelDesc: 'Système de réveil d’agent piloté par conditions : capteurs fichier/processus/port/HTTP/commande/webhook, les sessions en veille se réveillent automatiquement lorsque les conditions sont remplies ; enregistre l’onglet « Sentinel » affichant le tableau de surveillance global du serveur',

src/client/locales-hi.ts

@@ -17,6 +17,12 @@
 /** The hi dictionary (key-set-equal to zh, enforced by the type annotation in locales.ts). */
 export const hi: Record<string, string> = {
   files: 'फ़ाइलें',
+  guideDescFiles: 'वर्कस्पेस फ़ाइल ट्री देखें; क्लिक करने पर प्रीव्यू या संपादन खुलता है',
+  guideDescGit: 'Git बदलाव और इस सत्र के फ़ाइल बदलाव एक ही टैब में',
+  guideDescSubagent: 'सबएजेंट टोपोलॉजी और बैकग्राउंड कार्य, लाइव',
+  guideDescSidechat: 'इस सत्र का संदर्भ विरासत में लेने वाला स्वतंत्र फ़ॉलो-अप थ्रेड',
+  guideDescTerminal: 'असली शेल (xterm + pty), रीकनेक्ट सहित',
+  guideDescBrowser: 'अंतर्निहित ब्राउज़र, चैट के लिंक भी खोल सकता है',
   changesSessionEmpty: 'इस सत्र में अभी कोई फ़ाइल ऑपरेशन नहीं',
   changesRead: 'पढ़ना',
   changesMdReading: 'पठन',
@@ -100,6 +106,8 @@ export const hi: Record<string, string> = {
   terminalError: 'टर्मिनल कनेक्शन विफल',
   terminalConnectFailed: 'टर्मिनल बार-बार कनेक्ट विफल',
   terminalRetry: 'पुनः प्रयास',
+  terminalWaitBanner: 'एजेंट {needle} की प्रतीक्षा कर रहा है',
+  terminalSkipWait: 'प्रतीक्षा छोड़ें',
   terminalDepsFailed: 'टर्मिनल निर्भरता node-pty लोड विफल',
   terminalDepsHint: 'DSH मशीन पर एक टर्मिनल या cmd में नीचे दिया गया कमांड चलाएँ, फिर पुनः प्रयास करें (node-pty DSH कोर संस्करण के साथ सिंक रहता है):',
   terminalDepsProfile: ' (पहचाना गया प्रोफ़ाइल: {profile})',
@@ -395,7 +403,7 @@ export const hi: Record<string, string> = {
   addPluginsViewerCardDesc: 'फ़ाइल-प्रकार पूर्वावलोकन पंजीकृत करें',
   addPluginsTabDesc: 'साइडबार पृष्ठ (टैब) प्लगइन्स द्वारा विस्तारित हो सकते हैं। प्लगइन्स ctx.betterSidebar सेवा के माध्यम से पंजीकृत होते हैं; इंस्टॉल क्लिक करने पर इंस्टॉल कमांड कॉपी होता है — इसे उस टर्मिनल में पेस्ट करें जहाँ आपका DSH प्रोफ़ाइल है और चलाएँ।',
   addPluginsViewerDesc: 'फ़ाइल पूर्वावलोकक प्लगइन्स द्वारा विस्तारित हो सकते हैं। प्लगइन्स ctx.betterSidebar सेवा के माध्यम से पंजीकृत होते हैं; इंस्टॉल क्लिक करने पर इंस्टॉल कमांड कॉपी होता है — इसे उस टर्मिनल में पेस्ट करें जहाँ आपका DSH प्रोफ़ाइल है और चलाएँ।',
-  addPluginsBrowseMore: 'GitHub पर और प्लगइन्स देखें (topic: dsh-better-sidebar)',
+  addPluginsBrowseMore: 'GitHub पर और प्लगइन्स देखें (topic: dsh-apes-sidebar)',
   addPluginsSearch: 'प्लगइन नाम या विवरण से खोजें…',
   addPluginsNoMatch: 'कोई प्लगइन मेल नहीं खाता',
   addPluginsRecommended: 'अनुशंसित प्लगइन',
@@ -408,7 +416,7 @@ export const hi: Record<string, string> = {
   pluginGithubWorkbenchDesc: 'GitHub Workbench टैब: रिमोट रिपॉज़िटरी ट्री + Issues / Pull requests / Actions, पढ़ने के साथ-साथ पूर्ण लेखन समर्थन — Issue/PR बनाना, टिप्पणी करना, संपादन, बंद करना/पुनः खोलना, squash·merge·rebase मर्ज (पुष्टि अनिवार्य), CI पुनः चलाना/रद्द करना; रिपॉज़िटरी स्विचर स्वतः सुलभ रिपॉज़िटरी सूचीबद्ध करता है और सार्वजनिक रिपॉज़िटरी खोजता है; better-sidebar न होने पर स्वतंत्र दाईं ओर पैनल में फ़ॉलबैक होता है',
   pluginMdExportDesc: 'better-sidebar के Markdown टूलबार में "एक्सपोर्ट" बटन जोड़ता है: एक क्लिक में वर्तमान .md को स्टैंडअलोन HTML (टेबल/कोड ब्लॉक/Mermaid आरेख इनलाइन, लेआउट प्रीव्यू थीम का अनुसरण करता है) में रेंडर करके उसी फ़ोल्डर में सहेजता है, या प्रिंट डायलॉग से PDF निर्यात करता है',
   pluginCodeNavDesc: 'कोड प्रीव्यू नेविगेशन: फ़ाइल प्रकार से भाषा पहचानकर सिंटैक्स हाइलाइट, सिंबल आउटलाइन (क्लास/मेथड/वेरिएबल फ़िल्टर + एक-क्लिक जंप), फ़ाइल में खोज (सभी मैच हाइलाइट, पिछला/अगला, केस मैच) — better-sidebar एडिटर में कोड फ़ाइल प्रीव्यू संभालता है',
-  pluginSuhuangScrollDesc: 'स्थानीय Suhuang Scroll Runtime को DSH सेटिंग्स और better-sidebar से जोड़ता है, ताकि मॉडल कॉन्फ़िगरेशन, कनेक्शन परीक्षण और निरंतर ग्रेडिंग नियंत्रण उपलब्ध हों; Suhuang Scroll Runtime और dsh-better-sidebar आवश्यक हैं',
+  pluginSuhuangScrollDesc: 'स्थानीय Suhuang Scroll Runtime को DSH सेटिंग्स और better-sidebar से जोड़ता है, ताकि मॉडल कॉन्फ़िगरेशन, कनेक्शन परीक्षण और निरंतर ग्रेडिंग नियंत्रण उपलब्ध हों; Suhuang Scroll Runtime और dsh-apes-sidebar आवश्यक हैं',
   pluginBetterOverleafDesc: 'better-sidebar के लिए Overleaf टैब: सीधे CDP ब्राउज़र से लॉगिन (तीसरे पक्ष का Chromium समर्थित), प्रोजेक्ट सूची/स्विच, <workspace>/overleaf/ में स्थानीय git मिरर, रीड-ओनली API फ़ॉलबैक के साथ द्विदिश git सिंक, और फ़ाइल प्रीव्यू साइडबार वर्कबेंच से',
   pluginGitRemotesDesc: 'Git Remotes टैब: ब्रांच/अपस्ट्रीम/ahead-behind, fetch (वैकल्पिक prune), ff-only pull, और केवल टैब-में पुष्टि के बाद push। अंतर्निहित Git स्टेज/कमिट टैब को प्रतिस्थापित नहीं करता, और force-push या मॉडल ऑटो-push टूल नहीं देता',
   pluginSentinelDesc: 'स्थिति-संचालित एजेंट जागरूकता: फ़ाइल/प्रक्रिया/पोर्ट/http/कमांड/webhook सेंसर स्थितियाँ पूरी होने पर निष्क्रिय सत्र जगाते हैं; सर्वर-व्यापी वॉच टेबल के साथ "Sentinel" टैब पंजीकृत करता है',

src/client/locales-id.ts

@@ -15,6 +15,12 @@
 
 export const id: Record<string, string> = {
   files: 'Berkas',
+  guideDescFiles: 'Telusuri pohon berkas workspace; klik untuk pratinjau atau edit',
+  guideDescGit: 'Perubahan Git dan perubahan berkas sesi ini dalam satu tab',
+  guideDescSubagent: 'Topologi subagent dan tugas latar belakang, langsung',
+  guideDescSidechat: 'Utas lanjutan independen yang mewarisi konteks sesi ini',
+  guideDescTerminal: 'Shell sungguhan (xterm + pty), bisa menyambung ulang',
+  guideDescBrowser: 'Peramban tertanam, bisa mengambil alih tautan chat',
   changesSessionEmpty: 'Belum ada operasi file di sesi ini',
   changesRead: 'Baca',
   changesMdReading: 'Baca',
@@ -98,6 +104,8 @@ export const id: Record<string, string> = {
   terminalError: 'Koneksi terminal gagal',
   terminalConnectFailed: 'Terminal gagal terhubung berulang kali',
   terminalRetry: 'Coba lagi',
+  terminalWaitBanner: 'Agen menunggu {needle}',
+  terminalSkipWait: 'Lewati penungguan',
   terminalDepsFailed: 'Dependensi terminal node-pty gagal dimuat',
   terminalDepsHint: 'Jalankan perintah di bawah ini di terminal atau cmd pada mesin DSH untuk memperbaikinya, lalu coba lagi (node-pty tetap sinkron dengan versi inti DSH):',
   terminalDepsProfile: ' (profil terdeteksi: {profile})',
@@ -393,7 +401,7 @@ export const id: Record<string, string> = {
   addPluginsViewerCardDesc: 'Daftarkan pratinjau tipe berkas',
   addPluginsTabDesc: 'Halaman sidebar (tab) dapat diperluas oleh plugin. Plugin mendaftar melalui layanan ctx.betterSidebar; klik Install menyalin perintah instalasi — tempel ke terminal tempat profil DSH Anda berada dan jalankan.',
   addPluginsViewerDesc: 'Pratinjau berkas dapat diperluas oleh plugin. Plugin mendaftar melalui layanan ctx.betterSidebar; klik Install menyalin perintah instalasi — tempel ke terminal tempat profil DSH Anda berada dan jalankan.',
-  addPluginsBrowseMore: 'Jelajahi lebih banyak plugin di GitHub (topic: dsh-better-sidebar)',
+  addPluginsBrowseMore: 'Jelajahi lebih banyak plugin di GitHub (topic: dsh-apes-sidebar)',
   addPluginsSearch: 'Cari berdasarkan nama / deskripsi plugin…',
   addPluginsNoMatch: 'Tidak ada plugin yang cocok',
   addPluginsRecommended: 'Plugin yang direkomendasikan',
@@ -406,7 +414,7 @@ export const id: Record<string, string> = {
   pluginGithubWorkbenchDesc: 'Tab GitHub Workbench: pohon repo remote + Issues / Pull requests / Actions dengan dukungan tulis penuh — buat Issue/PR, komentar, edit, tutup/buka ulang, merge squash·merge·rebase (konfirmasi kuat), jalankan ulang/batalkan CI; pengalih repo otomatis mencantumkan repo yang dapat diakses dan mencari repo publik; tanpa better-sidebar otomatis beralih ke panel kanan mandiri',
   pluginMdExportDesc: 'Menambahkan tombol "Ekspor" ke bilah alat Markdown di better-sidebar: merender .md saat ini menjadi HTML mandiri dalam satu klik (tabel/blok kode/diagram Mermaid inline, tata letak mengikuti tema pratinjau) dan menyimpannya di folder yang sama, atau mengekspor ke PDF lewat dialog cetak',
   pluginCodeNavDesc: 'Navigasi pratinjau kode: mengenali bahasa dari jenis berkas dan menyorot sintaks, kerangka simbol (filter kelas/metode/variabel + lompat sekali klik), serta pencarian dalam berkas (sorot semua kecocokan, sebelum/berikutnya, peka huruf besar-kecil) — mengambil alih pratinjau berkas kode di editor better-sidebar',
-  pluginSuhuangScrollDesc: 'Menghubungkan Suhuang Scroll Runtime lokal ke pengaturan DSH dan better-sidebar untuk konfigurasi model, uji koneksi, dan kontrol penilaian berkelanjutan; memerlukan Suhuang Scroll Runtime dan dsh-better-sidebar',
+  pluginSuhuangScrollDesc: 'Menghubungkan Suhuang Scroll Runtime lokal ke pengaturan DSH dan better-sidebar untuk konfigurasi model, uji koneksi, dan kontrol penilaian berkelanjutan; memerlukan Suhuang Scroll Runtime dan dsh-apes-sidebar',
   pluginBetterOverleafDesc: 'Tab Overleaf untuk better-sidebar: login langsung lewat peramban CDP (mendukung Chromium pihak ketiga), daftar/pergantian proyek, mirror git lokal di <workspace>/overleaf/, sinkronisasi git dua arah dengan fallback API baca-saja, dan pratinjau berkas melalui workbench sidebar',
   pluginGitRemotesDesc: 'Tab Git Remotes: branch/upstream/ahead-behind, fetch (prune opsional), ff-only pull, dan push hanya setelah konfirmasi dalam tab. Tidak menggantikan tab stage/commit Git bawaan, dan tidak menawarkan force-push atau alat auto-push model',
   pluginSentinelDesc: 'Sistem bangun agen berbasis kondisi: sensor berkas/proses/port/http/perintah/webhook membangunkan sesi yang tidur saat kondisi terpicu; mendaftarkan tab "Sentinel" dengan tabel pengawasan server-wide',

src/client/locales-it.ts

@@ -3,11 +3,17 @@
  * consumed by the better-locale override store (see `locales.ts` for the
  * zh/en/ja lookup chain and the `attachBetterLocale` contract).
  *
- * @module dsh-better-sidebar/client/locales-it
+ * @module dsh-apes-sidebar/client/locales-it
  */
 
 export const it: Record<string, string> = {
   files: 'File',
+  guideDescFiles: 'Sfoglia l\'albero del workspace; un clic apre anteprima o editor',
+  guideDescGit: 'Modifiche Git e modifiche ai file di questa sessione in un solo tab',
+  guideDescSubagent: 'Topologia dei subagent e attività in background, in tempo reale',
+  guideDescSidechat: 'Un thread di approfondimento indipendente che eredita il contesto della sessione',
+  guideDescTerminal: 'Una vera shell (xterm + pty) con riconnessione',
+  guideDescBrowser: 'Browser integrato, può aprire i link della chat',
   changesSessionEmpty: 'Ancora nessuna operazione sui file in questa sessione',
   changesRead: 'Lettura',
   changesMdReading: 'Lettura',
@@ -91,6 +97,8 @@ export const it: Record<string, string> = {
   terminalError: 'Connessione del terminale non riuscita',
   terminalConnectFailed: 'Il terminale non è riuscito a connettersi più volte',
   terminalRetry: 'Riprova',
+  terminalWaitBanner: 'L’agente è in attesa di {needle}',
+  terminalSkipWait: 'Salta attesa',
   terminalDepsFailed: 'Caricamento della dipendenza del terminale node-pty non riuscito',
   terminalDepsHint: 'Esegua il comando seguente in un terminale o cmd sul computer DSH per ripristinarlo, poi riprovi (node-pty resta sincronizzato con la versione del core DSH):',
   terminalDepsProfile: ' (rilevato profilo: {profile})',
@@ -386,7 +394,7 @@ export const it: Record<string, string> = {
   addPluginsViewerCardDesc: 'Registri un’anteprima di tipo di file',
   addPluginsTabDesc: 'Le pagine della barra laterale (schede) possono essere estese dai plugin. I plugin si registrano tramite il servizio ctx.betterSidebar; cliccando Installa viene copiato il comando di installazione — lo incolli in un terminale dove risiede il profilo DSH e lo esegua.',
   addPluginsViewerDesc: 'I visualizzatori di file possono essere estesi dai plugin. I plugin si registrano tramite il servizio ctx.betterSidebar; cliccando Installa viene copiato il comando di installazione — lo incolli in un terminale dove risiede il profilo DSH e lo esegua.',
-  addPluginsBrowseMore: 'Sfogli altri plugin su GitHub (topic: dsh-better-sidebar)',
+  addPluginsBrowseMore: 'Sfogli altri plugin su GitHub (topic: dsh-apes-sidebar)',
   addPluginsSearch: 'Cerca per nome / descrizione del plugin…',
   addPluginsNoMatch: 'Nessun plugin corrispondente',
   addPluginsRecommended: 'Plugin consigliati',
@@ -399,7 +407,7 @@ export const it: Record<string, string> = {
   pluginGithubWorkbenchDesc: 'Scheda GitHub Workbench: albero del repository remoto + Issues / Pull requests / Actions con pieno supporto in scrittura — creazione di issue/PR, commenti, modifica, chiusura/riapertura, merge squash·merge·rebase (conferma rafforzata), riavvio/annullamento della CI; il selettore dei repository elenca automaticamente quelli accessibili e cerca tra quelli pubblici; senza better-sidebar esegue il fallback a un pannello laterale destro indipendente',
   pluginMdExportDesc: 'Aggiunge un pulsante «Esporta» alla barra degli strumenti Markdown di better-sidebar: con un clic esegue il rendering del .md corrente in HTML autonomo (tabelle/blocchi di codice/diagrammi Mermaid in linea, layout fedele al tema di anteprima) e lo salva accanto al .md, oppure esporta in PDF tramite la finestra di stampa',
   pluginCodeNavDesc: 'Navigazione dell’anteprima del codice: rileva il linguaggio dal tipo di file ed evidenzia la sintassi, struttura dei simboli (filtri classi/metodi/variabili + salto con un clic) e ricerca nel file (tutte le corrispondenze evidenziate, precedente/successiva, maiuscole/minuscole) — gestisce l’anteprima dei file di codice nell’editor better-sidebar',
-  pluginSuhuangScrollDesc: 'Collega il Runtime Suhuang Scroll locale alle impostazioni DSH e a better-sidebar per configurare il modello, testare la connessione e controllare la correzione continua; richiede Suhuang Scroll Runtime e dsh-better-sidebar',
+  pluginSuhuangScrollDesc: 'Collega il Runtime Suhuang Scroll locale alle impostazioni DSH e a better-sidebar per configurare il modello, testare la connessione e controllare la correzione continua; richiede Suhuang Scroll Runtime e dsh-apes-sidebar',
   pluginBetterOverleafDesc: 'Tab Overleaf per better-sidebar: accesso diretto tramite browser CDP (supporta Chromium di terze parti), elenco/cambio progetti, mirror git locali in <workspace>/overleaf/, sincronizzazione git bidirezionale con fallback API di sola lettura e anteprima dei file tramite la workbench della barra laterale',
   pluginGitRemotesDesc: 'Scheda Git Remotes: rami/upstream/ahead-behind, fetch (prune opzionale), pull ff-only e push solo dopo una conferma nella scheda. Non sostituisce la scheda stage/commit integrata di Git, e non offre force-push o uno strumento di push automatico del modello',
   pluginSentinelDesc: 'Sistema di risveglio dell’agente guidato da condizioni: sensori file/processo/porta/HTTP/comando/webhook risvegliano le sessioni dormienti quando le condizioni si verificano; registra una scheda «Sentinella» con la tabella di monitoraggio globale del server',

src/client/locales-ja.ts

@@ -17,6 +17,12 @@
 /** The ja dictionary (key-set-equal to zh, enforced by the type annotation in locales.ts). */
 export const ja: Record<string, string> = {
   files: 'ファイル',
+  guideDescFiles: 'ワークスペースのファイルツリーを閲覧し、クリックでプレビュー／編集',
+  guideDescGit: 'Git の変更と今回のセッションのファイル変更を 1 つのタブに',
+  guideDescSubagent: 'サブエージェントの構成とバックグラウンドタスクをリアルタイム表示',
+  guideDescSidechat: '現在のセッションの文脈を引き継ぐ独立した追加スレッド',
+  guideDescTerminal: '本物のシェル（xterm + pty）、再接続対応',
+  guideDescBrowser: '埋め込みブラウザ。チャット内のリンクも引き受け可能',
   changesSessionEmpty: 'このセッションにはファイル操作がまだありません',
   changesRead: '読み取り',
   changesMdReading: '閲覧',
@@ -100,6 +106,8 @@ export const ja: Record<string, string> = {
   terminalError: 'ターミナル接続に失敗',
   terminalConnectFailed: 'ターミナル接続が繰り返し失敗しました',
   terminalRetry: '再試行',
+  terminalWaitBanner: 'エージェントが {needle} を待機中',
+  terminalSkipWait: '待機をスキップ',
   terminalDepsFailed: 'ターミナル依存関係 node-pty の読み込みに失敗',
   terminalDepsHint: 'DSH 環境のターミナルまたは cmd で以下のコマンドを実行して修復し、再試行してください（node-pty は DSH コアと同じバージョンを維持）：',
   terminalDepsProfile: '（検出された profile：{profile}）',
@@ -395,7 +403,7 @@ export const ja: Record<string, string> = {
   addPluginsViewerCardDesc: '新しいファイル種別プレビューを登録',
   addPluginsTabDesc: 'サイドバーページ（Tab）はプラグインで拡張可能。プラグインは ctx.betterSidebar サービス経由で登録。「インストール」をクリックしてインストールコマンドをコピー、DSH 環境のターミナルに貼り付けて実行。',
   addPluginsViewerDesc: 'ファイルプレビューアーはプラグインで拡張可能。プラグインは ctx.betterSidebar サービス経由で登録。「インストール」をクリックしてインストールコマンドをコピー、DSH 環境のターミナルに貼り付けて実行。',
-  addPluginsBrowseMore: 'GitHub でプラグинをさらに閲覧（topic: dsh-better-sidebar）',
+  addPluginsBrowseMore: 'GitHub でプラグинをさらに閲覧（topic: dsh-apes-sidebar）',
   addPluginsSearch: 'プラグイン名 / 説明で検索…',
   addPluginsNoMatch: '一致するプラグインなし',
   addPluginsRecommended: '推奨プラグイン',
@@ -407,7 +415,7 @@ export const ja: Record<string, string> = {
   pluginFlowglassDesc: 'ライブセッションフローグラフ：ユーザー、アシスタント、ツール呼び出しの 3 レーン泳道、並列グループ、サブエージェント支線、ドリルダウン、ライブ状態をサポート。better-sidebar インストール時にネイティブ「Flowglass」Tab を登録、未インストール時は独立ドロワーを保持',
   pluginGitForgeDesc: 'better-sidebar「Git Forge」Tab：GitHub/Gitea 等 Forge アカウントライブラリ + プロジェクト単位の認可 + push ポリシー硬核拒絶。token はローカル secrets のみ、モデルコンテキストに入らない。読み取り専用 GitForge ツールと agent HTTPS credential helper を提供',
   pluginGithubWorkbenchDesc: 'better-sidebar「GitHub ワークベンチ」タブ:リモートリポジトリのツリー + Issues / Pull requests / Actions タブ。読み取りに加え、Issue・PR の作成、コメント、編集、クローズ/再オープン、squash・merge・rebase マージ(強確認)、CI の再実行/キャンセルに対応。リポジトリ切替ポップアップはアクセス可能なリポジトリを自動取得し、公開リポジトリの検索にも対応。better-sidebar 未導入時は独立右パネルへ自動フォールバック',
-  pluginSuhuangScrollDesc: 'ローカルの Suhuang Scroll Runtime を DSH 設定と better-sidebar に接続し、モデル設定、接続テスト、連続採点の操作を提供。Suhuang Scroll Runtime と dsh-better-sidebar が必要',
+  pluginSuhuangScrollDesc: 'ローカルの Suhuang Scroll Runtime を DSH 設定と better-sidebar に接続し、モデル設定、接続テスト、連続採点の操作を提供。Suhuang Scroll Runtime と dsh-apes-sidebar が必要',
   pluginBetterOverleafDesc: 'better-sidebar の Overleaf タブ：CDP ブラウザーに直接接続してログイン（サードパーティー Chromium 対応）、プロジェクト一覧/切替、<workspace>/overleaf/ のローカル git ミラー、双方向 git 同期（API 読み取り専用フォールバック）、ファイルプレビューはサイドバーのワークベンチを利用',
   pluginGitRemotesDesc: 'better-sidebar Git リモート Tab：ブランチ/アップストリーム/ahead-behind 表示、fetch（prune 可）、ff-only pull、確認後のみ push。内蔵 Git のステージ/コミットは置き換えず、force-push やモデル自動 push ツールは提供しない',
   pluginSentinelDesc: '条件駆動の agent 起動システム：ファイル/プロセス/ポート/HTTP/コマンド/webhook センサーが条件達成時に休眠会話を自動起動。「Sentinel」Tab を登録しサーバー全体の監視テーブルを表示',

src/client/locales-ko.ts

@@ -9,6 +9,12 @@
 
 export const ko: Record<string, string> = {
   files: '파일',
+  guideDescFiles: '워크스페이스 파일 트리를 보고 클릭하면 미리보기/편집',
+  guideDescGit: 'Git 변경 사항과 이번 세션의 파일 변경을 한 탭에서',
+  guideDescSubagent: '하위 에이전트 구조와 백그라운드 작업을 실시간으로',
+  guideDescSidechat: '현재 세션의 컨텍스트를 이어받는 독립 후속 스레드',
+  guideDescTerminal: '실제 셸(xterm + pty), 재연결 지원',
+  guideDescBrowser: '내장 브라우저, 채팅 링크도 대신 열 수 있음',
   changesSessionEmpty: '이 세션에 아직 파일 작업이 없습니다',
   changesRead: '읽기',
   changesMdReading: '읽기',
@@ -92,6 +98,8 @@ export const ko: Record<string, string> = {
   terminalError: '터미널 연결 실패',
   terminalConnectFailed: '터미널 연결이 여러 번 실패했습니다',
   terminalRetry: '다시 시도',
+  terminalWaitBanner: '에이전트가 {needle} 대기 중',
+  terminalSkipWait: '대기 건너뛰기',
   terminalDepsFailed: '터미널 의존성 node-pty 로드 실패',
   terminalDepsHint: 'DSH가 설치된 환경의 터미널 또는 cmd에서 아래 명령을 실행하여 복구한 후 다시 시도를 클릭하세요(node-pty는 DSH 코어와 동일한 버전을 유지합니다):',
   terminalDepsProfile: ' (profile 감지됨: {profile})',
@@ -387,7 +395,7 @@ export const ko: Record<string, string> = {
   addPluginsViewerCardDesc: '새 파일 형식 미리보기 등록',
   addPluginsTabDesc: '사이드바 페이지(Tab)는 플러그인으로 확장할 수 있습니다. 플러그인은 ctx.betterSidebar 서비스를 통해 등록합니다. "설치"를 클릭하면 설치 명령이 복사되며, DSH가 설치된 환경의 터미널에 붙여넣어 실행하세요.',
   addPluginsViewerDesc: '파일 미리보기는 플러그인으로 확장할 수 있습니다. 플러그인은 ctx.betterSidebar 서비스를 통해 등록합니다. "설치"를 클릭하면 설치 명령이 복사되며, DSH가 설치된 환경의 터미널에 붙여넣어 실행하세요.',
-  addPluginsBrowseMore: 'GitHub에서 더 많은 플러그인 보기(topic: dsh-better-sidebar)',
+  addPluginsBrowseMore: 'GitHub에서 더 많은 플러그인 보기(topic: dsh-apes-sidebar)',
   addPluginsSearch: '플러그인 이름 / 설명 검색…',
   addPluginsNoMatch: '일치하는 플러그인 없음',
   addPluginsRecommended: '추천 플러그인',
@@ -400,7 +408,7 @@ export const ko: Record<string, string> = {
   pluginGithubWorkbenchDesc: 'better-sidebar "GitHub Workbench" Tab: 원격 저장소 트리 + Issues / Pull requests / Actions 탭. 읽기 외에 Issue·PR 생성, 댓글, 편집, 닫기/다시 열기, squash·merge·rebase 병합(강한 확인), CI 재실행/취소를 지원합니다. 저장소 전환 팝업은 접근 가능한 저장소를 자동으로 가져오고 공개 저장소 검색도 지원합니다. better-sidebar 미설치 시 독립 우측 패널로 자동 폴백합니다',
   pluginMdExportDesc: 'better-sidebar의 Markdown 툴바에 "내보내기" 버튼을 추가: 클릭 한 번으로 현재 .md를 독립 실행형 HTML(표/코드 블록/Mermaid 다이어그램 인라인, 레이아웃은 미리보기 테마 따름)로 렌더링해 같은 폴더에 저장하거나, 인쇄 대화상자로 PDF를 내보냅니다',
   pluginCodeNavDesc: '코드 미리보기 내비게이션: 파일 형식으로 언어를 자동 인식해 구문 강조, 심볼 아웃라인(클래스/메서드/변수 필터 + 원클릭 이동), 파일 내 검색(모든 일치 강조, 이전/다음, 대소문자 구분) — better-sidebar 편집기의 코드 파일 미리보기를 대신 맡습니다',
-  pluginSuhuangScrollDesc: '로컬 Suhuang Scroll Runtime을 DSH 설정과 better-sidebar에 연결하여 모델 구성, 연결 테스트, 연속 채점 제어를 제공합니다. Suhuang Scroll Runtime과 dsh-better-sidebar가 필요합니다',
+  pluginSuhuangScrollDesc: '로컬 Suhuang Scroll Runtime을 DSH 설정과 better-sidebar에 연결하여 모델 구성, 연결 테스트, 연속 채점 제어를 제공합니다. Suhuang Scroll Runtime과 dsh-apes-sidebar가 필요합니다',
   pluginBetterOverleafDesc: 'better-sidebar의 Overleaf 탭: CDP 브라우저 직접 로그인(서드파티 Chromium 지원), 프로젝트 목록/전환, <workspace>/overleaf/ 로컬 git 미러, 읽기 전용 API 폴백이 있는 양방향 git 동기화, 파일 미리보기는 사이드바 워크벤치 사용',
   pluginGitRemotesDesc: 'better-sidebar Git 원격 Tab: 브랜치/업스트림/ahead-behind 확인, fetch(prune 가능), ff-only pull, 확인 후에만 push. 내장 Git의 스테이징/커밋을 대체하지 않으며, force-push나 모델 자동 push도 제공하지 않습니다',
   pluginSentinelDesc: '조건 기반 agent 웨이크업 시스템: 파일/프로세스/포트/HTTP/명령/webhook 센서가 조건을 충족하면 휴면 세션을 자동으로 깨웁니다. "센티널(哨兵)" Tab을 등록하여 서버 전역 모니터링 표를 보여줍니다',

src/client/locales-nl.ts

@@ -15,6 +15,12 @@
  */
 export const nl: Record<string, string> = {
   files: 'Bestanden',
+  guideDescFiles: 'Blader door de bestandsboom van de workspace; klik opent voorbeeld of editor',
+  guideDescGit: 'Git-wijzigingen en bestandswijzigingen van deze sessie in één tabblad',
+  guideDescSubagent: 'Subagent-topologie en achtergrondtaken, live',
+  guideDescSidechat: 'Een onafhankelijke vervolgthread met de context van deze sessie',
+  guideDescTerminal: 'Een echte shell (xterm + pty) met herverbinding',
+  guideDescBrowser: 'Ingebouwde browser die chatlinks kan overnemen',
   changesSessionEmpty: 'Nog geen bestandsbewerkingen in deze sessie',
   changesRead: 'Lezen',
   changesMdReading: 'Lezen',
@@ -98,6 +104,8 @@ export const nl: Record<string, string> = {
   terminalError: 'Terminalverbinding mislukt',
   terminalConnectFailed: 'Terminalverbinding herhaaldelijk mislukt',
   terminalRetry: 'Opnieuw proberen',
+  terminalWaitBanner: 'Agent wacht op {needle}',
+  terminalSkipWait: 'Wachten overslaan',
   terminalDepsFailed: 'Terminalafhankelijkheid node-pty kon niet worden geladen',
   terminalDepsHint: 'Voer het onderstaande commando uit in een terminal of cmd op de DSH-machine om het te herstellen en probeer het opnieuw (node-pty blijft in sync met de DSH-coreversie):',
   terminalDepsProfile: ' (gedetecteerde profile: {profile})',
@@ -393,7 +401,7 @@ export const nl: Record<string, string> = {
   addPluginsViewerCardDesc: 'Een bestandstype-preview registreren',
   addPluginsTabDesc: 'Zijbalkpagina\'s (tabbladen) kunnen door plugins worden uitgebreid. Plugins registreren via de ctx.betterSidebar-service; op Installeren klikken kopieert het installatiecommando — plak het in een terminal waar uw DSH-profiel zich bevindt en voer het uit.',
   addPluginsViewerDesc: 'Bestandsviewers kunnen door plugins worden uitgebreid. Plugins registreren via de ctx.betterSidebar-service; op Installeren klikken kopieert het installatiecommando — plak het in een terminal waar uw DSH-profiel zich bevindt en voer het uit.',
-  addPluginsBrowseMore: 'Meer plugins bekijken op GitHub (topic: dsh-better-sidebar)',
+  addPluginsBrowseMore: 'Meer plugins bekijken op GitHub (topic: dsh-apes-sidebar)',
   addPluginsSearch: 'Zoek op plugin-naam of -beschrijving…',
   addPluginsNoMatch: 'Geen plugins komen overeen',
   addPluginsRecommended: 'Aanbevolen plugins',
@@ -406,7 +414,7 @@ export const nl: Record<string, string> = {
   pluginGithubWorkbenchDesc: 'GitHub Workbench-tab: externe repositoryboom + Issues / Pull requests / Actions met volledige schrijfontsteuning — issue/PR aanmaken, reageren, bewerken, sluiten/heropenen, squash·merge·rebase-merge (sterke bevestiging), CI opnieuw uitvoeren/annuleren; de repo-wisselaar toont automatisch toegankelijke repo’s en doorzoekt openbare; zonder better-sidebar valt het terug op een zelfstandig rechterpaneel',
   pluginMdExportDesc: 'Voegt een knop «Exporteren» toe aan de Markdown-werkbalk van better-sidebar: rendert de huidige .md in één klik naar zelfstandige HTML (tabellen/codeblokken/Mermaid-diagrammen inline, lay-out volgt het voorbeeldthema) en slaat die naast het .md op, of exporteert via het afdrukvenster naar PDF',
   pluginCodeNavDesc: 'Codevoorbeeldnavigatie: detecteert de taal op bestandstype en kleurt de syntaxis, symbooloverzicht (filters voor klassen/methoden/variabelen + sprong met één klik) en zoeken in het bestand (alle treffers gemarkeerd, vorige/volgende, hoofdlettergevoelig) — neemt het codevoorbeeld in de better-sidebar-editor over',
-  pluginSuhuangScrollDesc: 'Verbindt de lokale Suhuang Scroll Runtime met DSH-instellingen en better-sidebar voor modelconfiguratie, verbindingstests en doorlopende beoordelingsbediening; vereist Suhuang Scroll Runtime en dsh-better-sidebar',
+  pluginSuhuangScrollDesc: 'Verbindt de lokale Suhuang Scroll Runtime met DSH-instellingen en better-sidebar voor modelconfiguratie, verbindingstests en doorlopende beoordelingsbediening; vereist Suhuang Scroll Runtime en dsh-apes-sidebar',
   pluginBetterOverleafDesc: 'Overleaf-tabblad voor better-sidebar: directe browserlogin via CDP (ondersteunt Chromium van derden), projectlijst/wisselen, lokale git-spiegels onder <workspace>/overleaf/, tweerichtingssynchronisatie met read-only-API-terugval en bestandsvoorbeeld via de sidebar-werkbank',
   pluginGitRemotesDesc: 'Git Remotes-tabblad: branch/upstream/ahead-behind, fetch (optioneel prune), ff-only pull, en push pas na een bevestiging in het tabblad. Vervangt het ingebouwde Git stage/commit-tabblad niet, en biedt geen force-push of een model-auto-push-tool',
   pluginSentinelDesc: 'Conditie-gedreven agent-wakeupsysteem: bestands/proces/poort/http/command/webhook-sensoren wekken slapende sessies wanneer condities af gaan; registreert een "Sentinel"-tabblad met de serverbrede watch-tabel',

src/client/locales-pl.ts

@@ -19,6 +19,12 @@
 /** The pl dictionary (key-set-equal to zh, enforced by the type annotation in locales.ts). */
 export const pl: Record<string, string> = {
   files: 'Pliki',
+  guideDescFiles: 'Przeglądaj drzewo plików obszaru roboczego; klik otwiera podgląd lub edycję',
+  guideDescGit: 'Zmiany Git i zmiany plików z tej sesji w jednej karcie',
+  guideDescSubagent: 'Topologia subagentów i zadania w tle na żywo',
+  guideDescSidechat: 'Niezależny wątek uzupełniający dziedziczący kontekst tej sesji',
+  guideDescTerminal: 'Prawdziwy shell (xterm + pty) z ponownym łączeniem',
+  guideDescBrowser: 'Wbudowana przeglądarka, może przejmować linki z czatu',
   changesSessionEmpty: 'Brak operacji na plikach w tej sesji',
   changesRead: 'Odczyt',
   changesMdReading: 'Czytanie',
@@ -102,6 +108,8 @@ export const pl: Record<string, string> = {
   terminalError: 'Połączenie z terminalem nie powiodło się',
   terminalConnectFailed: 'Terminal nie mógł połączyć się wielokrotnie',
   terminalRetry: 'Ponów',
+  terminalWaitBanner: 'Agent czeka na {needle}',
+  terminalSkipWait: 'Pomiń oczekiwanie',
   terminalDepsFailed: 'Zależność terminala node-pty nie mogła się załadować',
   terminalDepsHint: 'Uruchom poniższe polecenie w terminalu lub cmd na maszynie DSH, aby to naprawić, a następnie ponów (node-pty pozostaje w synchronizacji z wersją rdzenia DSH):',
   terminalDepsProfile: ' (wykryty profil: {profile})',
@@ -397,7 +405,7 @@ export const pl: Record<string, string> = {
   addPluginsViewerCardDesc: 'Zarejestruj podgląd typu pliku',
   addPluginsTabDesc: 'Strony panelu bocznego (karty) mogą być rozszerzane przez wtyczki. Wtyczki rejestrują się przez usługę ctx.betterSidebar; kliknięcie „Zainstaluj” kopiuje polecenie instalacji — wklej je do terminala tam, gdzie żyje Twój profil DSH, i uruchom.',
   addPluginsViewerDesc: 'Podglądy plików mogą być rozszerzane przez wtyczki. Wtyczki rejestrują się przez usługę ctx.betterSidebar; kliknięcie „Zainstaluj” kopiuje polecenie instalacji — wklej je do terminala tam, gdzie żyje Twój profil DSH, i uruchom.',
-  addPluginsBrowseMore: 'Przeglądaj więcej wtyczek na GitHub (topic: dsh-better-sidebar)',
+  addPluginsBrowseMore: 'Przeglądaj więcej wtyczek na GitHub (topic: dsh-apes-sidebar)',
   addPluginsSearch: 'Szukaj po nazwie lub opisie wtyczki…',
   addPluginsNoMatch: 'Brak pasujących wtyczek',
   addPluginsRecommended: 'Zalecane wtyczki',
@@ -410,7 +418,7 @@ export const pl: Record<string, string> = {
   pluginGithubWorkbenchDesc: 'Karta GitHub Workbench: drzewo zdalnego repozytorium + Issues / Pull requests / Actions z pełną obsługą zapisu — tworzenie issue/PR, komentowanie, edycja, zamykanie/ponowne otwieranie, scalanie squash·merge·rebase (mocne potwierdzenie), ponowne uruchomienie/anulowanie CI; przełącznik repozytoriów automatycznie wyświetla dostępne repozytoria i wyszukuje publiczne; bez better-sidebar następuje przejście na samodzielny panel po prawej stronie',
   pluginMdExportDesc: 'Dodaje przycisk „Eksportuj" do paska narzędzi Markdown w better-sidebar: jednym kliknięciem renderuje bieżący .md do samodzielnego HTML (tabele/bloki kodu/diagramy Mermaid w treści, układ zgodny z motywem podglądu) i zapisuje obok pliku .md albo eksportuje do PDF przez okno drukowania',
   pluginCodeNavDesc: 'Nawigacja podglądu kodu: rozpoznaje język po typie pliku i koloruje składnię, konspekt symboli (filtry klas/metod/zmiennych + skok jednym kliknięciem) oraz wyszukiwanie w pliku (podświetlanie wszystkich trafień, poprzedni/następny, rozróżnianie wielkości liter) — przejmuje podgląd plików kodu w edytorze better-sidebar',
-  pluginSuhuangScrollDesc: 'Łączy lokalny Suhuang Scroll Runtime z ustawieniami DSH i better-sidebar, zapewniając konfigurację modelu, test połączenia i sterowanie ciągłym ocenianiem; wymaga Suhuang Scroll Runtime i dsh-better-sidebar',
+  pluginSuhuangScrollDesc: 'Łączy lokalny Suhuang Scroll Runtime z ustawieniami DSH i better-sidebar, zapewniając konfigurację modelu, test połączenia i sterowanie ciągłym ocenianiem; wymaga Suhuang Scroll Runtime i dsh-apes-sidebar',
   pluginBetterOverleafDesc: 'Karta Overleaf dla better-sidebar: logowanie bezpośrednio przez przeglądarkę CDP (obsługa Chromium innych firm), lista/przełączanie projektów, lokalne kopie lustrzane git w <workspace>/overleaf/, dwukierunkowa synchronizacja git z awaryjnym API tylko do odczytu oraz podgląd plików przez warsztat panelu bocznego',
   pluginGitRemotesDesc: 'Karta Git Remotes: gałąź/nadrzędne/ahead-behind, fetch (z opcjonalnym prune), ff-only pull i push dopiero po potwierdzeniu w karcie. Nie zastępuje wbudowanej karty Git stage/commit i nie oferuje force-push ani narzędzia auto-push modelu',
   pluginSentinelDesc: 'Budzenie agenta sterowane warunkami: czujniki plików/procesów/portów/HTTP/poleceń/webhooków wybudzają uśpione sesje, gdy warunek zajdzie; rejestruje kartę „Sentinel” z ogólnoserwerową tabelą obserwacji',

src/client/locales-pt.ts

@@ -1,5 +1,11 @@
 export const pt: Record<string, string> = {
   files: 'Arquivos',
+  guideDescFiles: 'Navegue pela árvore do workspace; um clique abre a pré-visualização ou a edição',
+  guideDescGit: 'Alterações do Git e edições desta sessão em um único separador',
+  guideDescSubagent: 'Topologia de subagentes e tarefas em segundo plano, ao vivo',
+  guideDescSidechat: 'Uma conversa paralela independente que herda o contexto desta sessão',
+  guideDescTerminal: 'Um shell real (xterm + pty) com reconexão',
+  guideDescBrowser: 'Navegador incorporado, que pode abrir links do chat',
   changesSessionEmpty: 'Ainda sem operações de arquivo nesta sessão',
   changesRead: 'Leitura',
   changesMdReading: 'Leitura',
@@ -83,6 +89,8 @@ export const pt: Record<string, string> = {
   terminalError: 'Falha na conexão do terminal',
   terminalConnectFailed: 'O terminal falhou ao conectar repetidamente',
   terminalRetry: 'Tentar novamente',
+  terminalWaitBanner: 'O agente está aguardando {needle}',
+  terminalSkipWait: 'Pular espera',
   terminalDepsFailed: 'A dependência do terminal node-pty falhou ao carregar',
   terminalDepsHint: 'Execute o comando abaixo em um terminal ou cmd na máquina do DSH para reparar e tente novamente (node-pty permanece em sincronia com a versão do núcleo do DSH):',
   terminalDepsProfile: ' (perfil detectado: {profile})',
@@ -378,7 +386,7 @@ export const pt: Record<string, string> = {
   addPluginsViewerCardDesc: 'Registrar uma pré-visualização de tipo de arquivo',
   addPluginsTabDesc: 'As páginas da barra lateral (abas) podem ser estendidas por plugins. Os plugins registram pelo serviço ctx.betterSidebar; clicar em Instalar copia o comando de instalação — cole-o em um terminal onde seu perfil do DSH vive e execute.',
   addPluginsViewerDesc: 'Os visualizadores de arquivos podem ser estendidos por plugins. Os plugins registram pelo serviço ctx.betterSidebar; clicar em Instalar copia o comando de instalação — cole-o em um terminal onde seu perfil do DSH vive e execute.',
-  addPluginsBrowseMore: 'Navegue por mais plugins no GitHub (topic: dsh-better-sidebar)',
+  addPluginsBrowseMore: 'Navegue por mais plugins no GitHub (topic: dsh-apes-sidebar)',
   addPluginsSearch: 'Pesquisar por nome ou descrição do plugin…',
   addPluginsNoMatch: 'Nenhum plugin corresponde',
   addPluginsRecommended: 'Plugins recomendados',
@@ -391,7 +399,7 @@ export const pt: Record<string, string> = {
   pluginGithubWorkbenchDesc: 'Aba GitHub Workbench: árvore do repositório remoto + Issues / Pull requests / Actions com suporte completo de escrita — criar Issue/PR, comentar, editar, fechar/reabrir, merge squash·merge·rebase (confirmação reforçada), reexecutar/cancelar CI; o seletor de repositórios lista automaticamente os repositórios acessíveis e busca nos públicos; sem better-sidebar, faz fallback para um painel lateral direito independente',
   pluginMdExportDesc: 'Adiciona um botão «Exportar» à barra de ferramentas do Markdown no better-sidebar: com um clique, renderiza o .md atual em HTML autônomo (tabelas/blocos de código/diagramas Mermaid embutidos, layout seguindo o tema de pré-visualização) e salva na mesma pasta, ou exporta para PDF pela caixa de impressão',
   pluginCodeNavDesc: 'Navegação de pré-visualização de código: detecta a linguagem pelo tipo de arquivo e destaca a sintaxe, contorno de símbolos (filtros de classes/métodos/variáveis + salto em um clique) e busca no arquivo (todas as ocorrências destacadas, anterior/próxima, diferenciando maiúsculas) — assume a pré-visualização de arquivos de código no editor do better-sidebar',
-  pluginSuhuangScrollDesc: 'Conecta o Suhuang Scroll Runtime local às configurações do DSH e ao better-sidebar para configurar o modelo, testar a conexão e controlar a correção contínua; requer Suhuang Scroll Runtime e dsh-better-sidebar',
+  pluginSuhuangScrollDesc: 'Conecta o Suhuang Scroll Runtime local às configurações do DSH e ao better-sidebar para configurar o modelo, testar a conexão e controlar a correção contínua; requer Suhuang Scroll Runtime e dsh-apes-sidebar',
   pluginBetterOverleafDesc: 'Aba Overleaf para better-sidebar: login direto pelo navegador via CDP (compatível com Chromium de terceiros), lista/troca de projetos, espelhos git locais em <workspace>/overleaf/, sincronização git bidirecional com fallback de API somente leitura e pré-visualização de arquivos pela bancada da barra lateral',
   pluginGitRemotesDesc: 'Aba de remotos Git: branch/upstream/ahead-behind, fetch (prune opcional), pull ff-only e push apenas após confirmar na aba. Não substitui a aba interna de stage/commit do Git e não oferece force-push nem push automático pelo modelo',
   pluginSentinelDesc: 'Despertar de agentes dirigido por condições: sensores de arquivo/processo/porta/HTTP/comando/webhook acordam sessões adormecidas quando as condições disparam; registra uma aba "Sentinelas" com a tabela de monitoramento global do servidor',

src/client/locales-ru.ts

@@ -13,6 +13,12 @@
 
 export const ru: Record<string, string> = {
   files: 'Файлы',
+  guideDescFiles: 'Дерево файлов рабочей области: клик открывает просмотр или редактор',
+  guideDescGit: 'Изменения Git и правки файлов этой сессии в одной вкладке',
+  guideDescSubagent: 'Топология субагентов и фоновые задачи в реальном времени',
+  guideDescSidechat: 'Независимый дополнительный тред с контекстом этой сессии',
+  guideDescTerminal: 'Настоящий shell (xterm + pty) с переподключением',
+  guideDescBrowser: 'Встроенный браузер, перехватывает ссылки из чата',
   changesSessionEmpty: 'В этой сессии пока нет файловых операций',
   changesRead: 'Чтение',
   changesMdReading: 'Чтение',
@@ -96,6 +102,8 @@ export const ru: Record<string, string> = {
   terminalError: 'Сбой подключения терминала',
   terminalConnectFailed: 'Терминал не смог подключиться после нескольких попыток',
   terminalRetry: 'Повторить',
+  terminalWaitBanner: 'Агент ожидает {needle}',
+  terminalSkipWait: 'Пропустить ожидание',
   terminalDepsFailed: 'Не удалось загрузить зависимость терминала node-pty',
   terminalDepsHint: 'Выполните приведённую ниже команду в терминале или cmd на машине DSH, затем нажмите «Повторить» (node-pty остаётся синхронизированным с версией ядра DSH):',
   terminalDepsProfile: ' (обнаружен profile: {profile})',
@@ -393,7 +401,7 @@ export const ru: Record<string, string> = {
   addPluginsViewerCardDesc: 'Зарегистрировать предпросмотр типа файлов',
   addPluginsTabDesc: 'Страницы боковой панели (вкладки) расширяются плагинами. Плагины регистрируются через службу ctx.betterSidebar; щелчок по «Установить» копирует команду — вставьте её в терминал, где находится профиль DSH, и выполните.',
   addPluginsViewerDesc: 'Просмотрщики файлов расширяются плагинами. Плагины регистрируются через службу ctx.betterSidebar; щелчок по «Установить» копирует команду — вставьте её в терминал, где находится профиль DSH, и выполните.',
-  addPluginsBrowseMore: 'Найти больше плагинов на GitHub (topic: dsh-better-sidebar)',
+  addPluginsBrowseMore: 'Найти больше плагинов на GitHub (topic: dsh-apes-sidebar)',
   addPluginsSearch: 'Поиск по имени или описанию плагина…',
   addPluginsNoMatch: 'Нет совпадающих плагинов',
   addPluginsRecommended: 'Рекомендуемые плагины',
@@ -406,7 +414,7 @@ export const ru: Record<string, string> = {
   pluginGithubWorkbenchDesc: 'Вкладка «GitHub Workbench»: дерево удалённого репозитория + Issues / Pull requests / Actions с полной поддержкой записи — создание Issue/PR, комментарии, редактирование, закрытие/повторное открытие, merge squash·merge·rebase (с сильным подтверждением), перезапуск/отмена CI; переключатель репозиториев автоматически показывает доступные репозитории и ищет по публичным; без better-sidebar используется отдельная правая панель',
   pluginMdExportDesc: 'Добавляет кнопку «Экспорт» на панель инструментов Markdown в better-sidebar: одним кликом рендерит текущий .md в самостоятельный HTML (таблицы/блоки кода/Mermaid-диаграммы встроены, вёрстка следует теме предпросмотра) и сохраняет рядом с .md либо экспортирует в PDF через диалог печати',
   pluginCodeNavDesc: 'Навигация по предпросмотру кода: определяет язык по типу файла и подсвечивает синтаксис, схема символов (фильтры классов/методов/переменных + переход в один клик) и поиск по файлу (подсветка всех совпадений, назад/вперёд, учёт регистра) — берёт на себя предпросмотр файлов кода в редакторе better-sidebar',
-  pluginSuhuangScrollDesc: 'Подключает локальный Suhuang Scroll Runtime к настройкам DSH и better-sidebar для настройки модели, проверки соединения и управления непрерывной проверкой; требуются Suhuang Scroll Runtime и dsh-better-sidebar',
+  pluginSuhuangScrollDesc: 'Подключает локальный Suhuang Scroll Runtime к настройкам DSH и better-sidebar для настройки модели, проверки соединения и управления непрерывной проверкой; требуются Suhuang Scroll Runtime и dsh-apes-sidebar',
   pluginBetterOverleafDesc: 'Вкладка Overleaf для better-sidebar: вход напрямую через CDP-браузер (поддержка стороннего Chromium), список/переключение проектов, локальные git-зеркала в <workspace>/overleaf/, двунаправленная синхронизация git с откатом к API только для чтения, просмотр файлов через рабочую панель сайдбара',
   pluginGitRemotesDesc: 'Вкладка Git Remotes: просмотр веток/апстрима/ahead-behind, fetch (с возможностью prune), ff-only pull и push только после подтверждения во вкладке. Не заменяет встроенную вкладку Git (индексирование/коммит), не предоставляет force-push и инструмент авто-push для модели',
   pluginSentinelDesc: 'Система пробуждения агента по условиям: сенсоры файлов/процессов/портов/HTTP/команд/webhook будят спящие сессии при срабатывании; регистрирует вкладку «Sentinel» с глобальной таблицей наблюдений сервера',

src/client/locales-sv.ts

@@ -1,5 +1,11 @@
 export const sv: Record<string, string> = {
   files: 'Filer',
+  guideDescFiles: 'Bläddra i arbetsytans filträd; klick öppnar förhandsvisning eller redigering',
+  guideDescGit: 'Git-ändringar och sessionens filändringar i en flik',
+  guideDescSubagent: 'Subagenttopologi och bakgrundsjobb, live',
+  guideDescSidechat: 'En oberoende uppföljningstråd som ärver sessionens kontext',
+  guideDescTerminal: 'Ett riktigt skal (xterm + pty) med återanslutning',
+  guideDescBrowser: 'Inbäddad webbläsare som kan ta över chattlänkar',
   changesSessionEmpty: 'Inga filoperationer i den här sessionen ännu',
   changesRead: 'Läs',
   changesMdReading: 'Läsning',
@@ -83,6 +89,8 @@ export const sv: Record<string, string> = {
   terminalError: 'Terminalanslutning misslyckades',
   terminalConnectFailed: 'Terminal misslyckades att ansluta upprepade gånger',
   terminalRetry: 'Försök igen',
+  terminalWaitBanner: 'Agenten väntar på {needle}',
+  terminalSkipWait: 'Hoppa över väntan',
   terminalDepsFailed: 'Terminalberoendet node-pty kunde inte laddas',
   terminalDepsHint: 'Kör kommandot nedan i en terminal eller cmd på DSH-maskinen för att reparera det, försök sedan igen (node-pty hålls synkad med DSH-kärnversionen):',
   terminalDepsProfile: ' (upptäckt profil: {profile})',
@@ -378,7 +386,7 @@ export const sv: Record<string, string> = {
   addPluginsViewerCardDesc: 'Registrera en filtypsförhandsgranskning',
   addPluginsTabDesc: 'Sidopanelens sidor (flikar) kan utökas av plugins. Plugins registreras via ctx.betterSidebar-tjänsten; att klicka på Installera kopierar installationskommandot — klistra in det i en terminal där er DSH-profil lever och kör det.',
   addPluginsViewerDesc: 'Filförhandsgranskare kan utökas av plugins. Plugins registreras via ctx.betterSidebar-tjänsten; att klicka på Installera kopierar installationskommandot — klistra in det i en terminal där er DSH-profil lever och kör det.',
-  addPluginsBrowseMore: 'Bläddra bland fler plugins på GitHub (topic: dsh-better-sidebar)',
+  addPluginsBrowseMore: 'Bläddra bland fler plugins på GitHub (topic: dsh-apes-sidebar)',
   addPluginsSearch: 'Sök på plugin-namn eller beskrivning…',
   addPluginsNoMatch: 'Inga plugins matchar',
   addPluginsRecommended: 'Rekommenderade plugins',
@@ -391,7 +399,7 @@ export const sv: Record<string, string> = {
   pluginGithubWorkbenchDesc: 'GitHub Workbench-flik: fjärrrepo-träd + Issues / Pull requests / Actions med fullt skrivstöd — skapa issue/PR, kommentera, redigera, stäng/öppna igen, squash·merge·rebase-merge (stark bekräftelse), kör om/avbryt CI; repoväxlaren listar automatiskt tillgängliga repon och söker i publika; utan better-sidebar växlar den till en fristående höger panel',
   pluginMdExportDesc: 'Lägger till en «Exportera»-knapp i Markdown-verktygsfältet i better-sidebar: renderar nuvarande .md till fristående HTML i ett klick (tabeller/kodblock/Mermaid-diagram inline, layout följer förhandsvisningstemat) och sparar bredvid .md-filen, eller exporterar till PDF via utskriftsdialogen',
   pluginCodeNavDesc: 'Kodförhandsvisningsnavigering: känner automatiskt av språket från filtypen och färglägger syntaxen, symbolöversikt (filter för klasser/metoder/variabler + hopp med ett klick) och filsökning (markera alla träffar, föregående/nästa, skiftlägeskänsligt) — tar över kodfilförhandsvisning i better-sidebar-redigeraren',
-  pluginSuhuangScrollDesc: 'Ansluter den lokala Suhuang Scroll Runtime till DSH-inställningar och better-sidebar för modellkonfiguration, anslutningstest och styrning av kontinuerlig rättning; kräver Suhuang Scroll Runtime och dsh-better-sidebar',
+  pluginSuhuangScrollDesc: 'Ansluter den lokala Suhuang Scroll Runtime till DSH-inställningar och better-sidebar för modellkonfiguration, anslutningstest och styrning av kontinuerlig rättning; kräver Suhuang Scroll Runtime och dsh-apes-sidebar',
   pluginBetterOverleafDesc: 'Overleaf-flik för better-sidebar: direktinloggning via CDP-webbläsare (stöd för tredjeparts-Chromium), projektlista/byte, lokala git-speglar under <workspace>/overleaf/, dubbelriktad git-synk med read-only-API-fallback och förhandsvisning av filer via sidofältets workbench',
   pluginGitRemotesDesc: 'Git Remotes-flik: gren/upstream/ahead-behind, fetch (valbar prune), ff-only pull och push endast efter bekräftelse i fliken. Ersätter inte den inbyggda Git-köa/commit-fliken, och erbjuder inte force-push eller ett model-auto-push-verktyg',
   pluginSentinelDesc: 'Villkorsdriven agentväckning: fil-/process-/port-/http-/kommando-/webhook-sensorer väcker vilande sessioner när villkor utlöses; registrerar en "Sentinel"-flik med serverns globala bevakningstabell',

src/client/locales-th.ts

@@ -17,6 +17,12 @@
 /** The th dictionary (key-set-equal to zh, enforced by the type annotation in locales.ts). */
 export const th: Record<string, string> = {
   files: 'ไฟล์',
+  guideDescFiles: 'เรียกดูแผนผังไฟล์ของเวิร์กสเปซ คลิกเพื่อดูตัวอย่างหรือแก้ไข',
+  guideDescGit: 'การเปลี่ยนแปลง Git และไฟล์ที่แก้ในเซสชันนี้ในแท็บเดียว',
+  guideDescSubagent: 'โครงสร้างซับเอเจนต์และงานเบื้องหลังแบบเรียลไทม์',
+  guideDescSidechat: 'เธรดถามต่ออิสระที่สืบทอดบริบทของเซสชันนี้',
+  guideDescTerminal: 'เชลล์จริง (xterm + pty) เชื่อมต่อใหม่ได้',
+  guideDescBrowser: 'เบราว์เซอร์ในตัว รับช่วงลิงก์จากแชทได้',
   changesSessionEmpty: 'ยังไม่มีการดำเนินการไฟล์ในเซสชันนี้',
   changesRead: 'อ่าน',
   changesMdReading: 'อ่าน',
@@ -100,6 +106,8 @@ export const th: Record<string, string> = {
   terminalError: 'การเชื่อมต่อเทอร์มินัลล้มเหลว',
   terminalConnectFailed: 'เทอร์มินัลเชื่อมต่อล้มเหลวหลายครั้ง',
   terminalRetry: 'ลองอีกครั้ง',
+  terminalWaitBanner: 'เอเจนต์กำลังรอ {needle}',
+  terminalSkipWait: 'ข้ามการรอ',
   terminalDepsFailed: 'การอ้างอิงเทอร์มินัล node-pty โหลดล้มเหลว',
   terminalDepsHint: 'เรียกใช้คำสั่งด้านล่างในเทอร์มินัลหรือ cmd บนเครื่อง DSH เพื่อซ่อมแซม แล้วกดลองอีกครั้ง (node-pty ต้องซิงค์กับเวอร์ชันหลักของ DSH):',
   terminalDepsProfile: ' (ตรวจพบ profile: {profile})',
@@ -395,7 +403,7 @@ export const th: Record<string, string> = {
   addPluginsViewerCardDesc: 'ลงทะเบียนพรีวิวประเภทไฟล์',
   addPluginsTabDesc: 'หน้าแถบด้านข้าง (tab) สามารถขยายได้ด้วยปลั๊กอิน ปลั๊กอินลงทะเบียนผ่านบริการ ctx.betterSidebar; การคลิก Install จะคัดลอกคำสั่งติดตั้ง — วางลงในเทอร์มินัลที่ DSH profile ของคุณอยู่แล้วเรียกใช้',
   addPluginsViewerDesc: 'ตัวพรีวิวไฟล์สามารถขยายได้ด้วยปลั๊กอิน ปลั๊กอินลงทะเบียนผ่านบริการ ctx.betterSidebar; การคลิก Install จะคัดลอกคำสั่งติดตั้ง — วางลงในเทอร์มินัลที่ DSH profile ของคุณอยู่แล้วเรียกใช้',
-  addPluginsBrowseMore: 'เรียกดูปลั๊กอินเพิ่มเติมบน GitHub (topic: dsh-better-sidebar)',
+  addPluginsBrowseMore: 'เรียกดูปลั๊กอินเพิ่มเติมบน GitHub (topic: dsh-apes-sidebar)',
   addPluginsSearch: 'ค้นหาตามชื่อหรือคำอธิบายปลั๊กอิน…',
   addPluginsNoMatch: 'ไม่มีปลั๊กอินที่ตรง',
   addPluginsRecommended: 'ปลั๊กอินแนะนำ',
@@ -408,7 +416,7 @@ export const th: Record<string, string> = {
   pluginGithubWorkbenchDesc: 'แท็บ GitHub Workbench: โครงสร้าง repo รีโมต + Issues / Pull requests / Actions พร้อมรองรับการเขียนครบวงจร — สร้าง Issue/PR, แสดงความคิดเห็น, แก้ไข, ปิด/เปิดใหม่, รวมแบบ squash·merge·rebase (ยืนยันก่อนเสมอ), รัน/ยกเลิก CI ใหม่; ตัวสลับ repo จะดึงรายการ repo ที่มีสิทธิ์เข้าถึงโดยอัตโนมัติและค้นหา repo สาธารณะได้; หากไม่ได้ติดตั้ง better-sidebar จะสลับไปใช้แผงด้านขวาแบบสแตนด์อโลนอัตโนมัติ',
   pluginMdExportDesc: 'เพิ่มปุ่ม "ส่งออก" ในแถบเครื่องมือ Markdown ของ better-sidebar: เรนเดอร์ .md ปัจจุบันเป็น HTML แบบสแตนด์อโลนในคลิกเดียว (ตาราง/บล็อกโค้ด/ไดอะแกรม Mermaid แบบอินไลน์ เลย์เอาต์ตามธีมพรีวิว) แล้วบันทึกไว้โฟลเดอร์เดียวกัน หรือส่งออกเป็น PDF ผ่านกล่องโต้ตอบการพิมพ์',
   pluginCodeNavDesc: 'การนำทางพรีวิวโค้ด: ระบุภาษาอัตโนมัติจากประเภทไฟล์และไฮไลต์ไวยากรณ์ โครงร่างสัญลักษณ์ (กรองคลาส/เมธอด/ตัวแปร + กระโดดคลิกเดียว) และค้นหาในไฟล์ (ไฮไลต์ทุกจุดที่ตรง ก่อนหน้า/ถัดไป แยกตัวพิมพ์ใหญ่เล็ก) — รับช่วงพรีวิวไฟล์โค้ดในตัวแก้ไข better-sidebar',
-  pluginSuhuangScrollDesc: 'เชื่อมต่อ Suhuang Scroll Runtime ในเครื่องกับการตั้งค่า DSH และ better-sidebar สำหรับการกำหนดค่าโมเดล การทดสอบการเชื่อมต่อ และการควบคุมการตรวจงานต่อเนื่อง โดยต้องติดตั้ง Suhuang Scroll Runtime และ dsh-better-sidebar',
+  pluginSuhuangScrollDesc: 'เชื่อมต่อ Suhuang Scroll Runtime ในเครื่องกับการตั้งค่า DSH และ better-sidebar สำหรับการกำหนดค่าโมเดล การทดสอบการเชื่อมต่อ และการควบคุมการตรวจงานต่อเนื่อง โดยต้องติดตั้ง Suhuang Scroll Runtime และ dsh-apes-sidebar',
   pluginBetterOverleafDesc: 'แท็บ Overleaf สำหรับ better-sidebar: เข้าสู่ระบบผ่านเบราว์เซอร์ CDP โดยตรง (รองรับ Chromium ของบุคคลที่สาม) รายการ/สลับโปรเจกต์ มิเรอร์ git ภายในเครื่องที่ <workspace>/overleaf/ ซิงก์ git สองทางพร้อมสำรองแบบ API อ่านอย่างเดียว และดูตัวอย่างไฟล์ผ่านเวิร์กเบนช์ของแถบข้าง',
   pluginGitRemotesDesc: 'tab Git Remotes: branch/upstream/ahead-behind, fetch (optional prune), ff-only pull และ push หลังการยืนยันใน tab เท่านั้น ไม่แทนที่ tab stage/commit ของ Git แบบ built-in และไม่เสนอ force-push หรือเครื่องมือ auto-push ของโมเดล',
   pluginSentinelDesc: 'การปลุกตัวแทนที่ขับเคลื่อนด้วยเงื่อนไข: เซนเซอร์ file/process/port/http/command/webhook ปลุกเซสชันที่หลับเมื่อเงื่อนไขเกิดขึ้น; ลงทะเบียน tab "Sentinel" พร้อมตารางเฝ้าระวังทั่วทั้งเซิร์ฟเวอร์',

src/client/locales-tr.ts

@@ -17,6 +17,12 @@
 /** The tr dictionary (key-set-equal to zh, enforced by the type annotation in locales.ts). */
 export const tr: Record<string, string> = {
   files: 'Dosyalar',
+  guideDescFiles: 'Çalışma alanı dosya ağacına göz atın; tıklayınca önizleme veya düzenleme açılır',
+  guideDescGit: 'Git değişiklikleri ve bu oturumun dosya değişiklikleri tek sekmede',
+  guideDescSubagent: 'Alt ajan topolojisi ve arka plan görevleri, canlı',
+  guideDescSidechat: 'Bu oturumun bağlamını devralan bağımsız bir yan konu',
+  guideDescTerminal: 'Gerçek bir shell (xterm + pty), yeniden bağlanma destekli',
+  guideDescBrowser: 'Sohbet bağlantılarını devralabilen gömülü tarayıcı',
   changesSessionEmpty: 'Bu oturumda henüz dosya işlemi yok',
   changesRead: 'Okuma',
   changesMdReading: 'Okuma',
@@ -100,6 +106,8 @@ export const tr: Record<string, string> = {
   terminalError: 'Terminal bağlantısı başarısız',
   terminalConnectFailed: 'Terminal art arda bağlanamadı',
   terminalRetry: 'Yeniden dene',
+  terminalWaitBanner: 'Ajan {needle} bekliyor',
+  terminalSkipWait: 'Beklemeyi atla',
   terminalDepsFailed: 'Terminal bağımlılığı node-pty yüklenemedi',
   terminalDepsHint: 'Onarmak için DSH makinesindeki bir terminalde veya cmd’de aşağıdaki komutu çalıştırın, sonra yeniden deneyin (node-pty, DSH çekirdek sürümüyle senkron kalır):',
   terminalDepsProfile: ' (algılanan profil: {profile})',
@@ -395,7 +403,7 @@ export const tr: Record<string, string> = {
   addPluginsViewerCardDesc: 'Yeni bir dosya türü önizlemesi kaydet',
   addPluginsTabDesc: 'Kenar çubuğu sayfaları (sekmeler) eklentilerce genişletilebilir. Eklentiler ctx.betterSidebar hizmeti aracılığıyla kaydolur; Yükle’ye tıklamak kurulum komutunu kopyalar — DSH profilinizin yaşadığı bir terminale yapıştırın ve çalıştırın.',
   addPluginsViewerDesc: 'Dosya önizleyicileri eklentilerce genişletilebilir. Eklentiler ctx.betterSidebar hizmeti aracılığıyla kaydolur; Yükle’ye tıklamak kurulum komutunu kopyalar — DSH profilinizin yaşadığı bir terminale yapıştırın ve çalıştırın.',
-  addPluginsBrowseMore: 'GitHub’da daha fazla eklentiye göz atın (topic: dsh-better-sidebar)',
+  addPluginsBrowseMore: 'GitHub’da daha fazla eklentiye göz atın (topic: dsh-apes-sidebar)',
   addPluginsSearch: 'Eklenti adı / açıklamasına göre ara…',
   addPluginsNoMatch: 'Eşleşen eklenti yok',
   addPluginsRecommended: 'Önerilen eklentiler',
@@ -408,7 +416,7 @@ export const tr: Record<string, string> = {
   pluginGithubWorkbenchDesc: 'GitHub Workbench sekmesi: uzak depo ağacı + Issues / Pull requests / Actions tam yazma desteğiyle — Issue/PR oluşturma, yorum yapma, düzenleme, kapatma/yeniden açma, squash·merge·rebase birleştirme (güçlü onay), CI’yi yeniden çalıştırma/iptal etme; repo değiştirici erişilebilir depoları otomatik listeler ve genel depolarda arama yapar; better-sidebar yoksa bağımsız sağ panele geri düşer',
   pluginMdExportDesc: 'better-sidebar Markdown araç çubuğuna «Dışa aktar» düğmesi ekler: geçerli .md dosyasını tek tıkla bağımsız HTML biçimine dönüştürür (tablolar/kod blokları/Mermaid diyagramları gömülü, düzen önizleme temasını izler) ve .md dosyasının yanına kaydeder ya da yazdırma penceresinden PDF dışa aktarır',
   pluginCodeNavDesc: 'Kod önizleme gezinmesi: dosya türünden dili otomatik algılayıp söz dizimini vurgular, simge şeması (sınıf/yöntem/değişken filtreleri + tek tıkla atlama) ve dosya içi arama (tüm eşleşmeleri vurgula, önceki/sonraki, büyük/küçük harf duyarlı) — better-sidebar düzenleyicisinde kod dosyası önizlemesini devralır',
-  pluginSuhuangScrollDesc: 'Yerel Suhuang Scroll Runtime ortamını model yapılandırması, bağlantı testi ve kesintisiz değerlendirme denetimi için DSH ayarlarına ve better-sidebar öğesine bağlar; Suhuang Scroll Runtime ve dsh-better-sidebar gerektirir',
+  pluginSuhuangScrollDesc: 'Yerel Suhuang Scroll Runtime ortamını model yapılandırması, bağlantı testi ve kesintisiz değerlendirme denetimi için DSH ayarlarına ve better-sidebar öğesine bağlar; Suhuang Scroll Runtime ve dsh-apes-sidebar gerektirir',
   pluginBetterOverleafDesc: 'better-sidebar için Overleaf sekmesi: doğrudan CDP tarayıcı girişi (üçüncü taraf Chromium destekli), proje listesi/geçiş, <workspace>/overleaf/ altında yerel git aynaları, salt okunur API yedekli çift yönlü git senkronizasyonu ve dosya önizlemesi kenar çubuğu workbench üzerinden',
   pluginGitRemotesDesc: 'Git Remotes sekmesi: dal/yukarı akış/ahead-behind, fetch (isteğe bağlı prune), ff-only pull ve yalnızca sekme içi onaydan sonra push. Yerleşik Git sahnele/işle sekmesini değiştirmez; force-push veya model otomatik push aracı sunmaz',
   pluginSentinelDesc: 'Koşul odaklı aracı uyandırma: dosya/süreç/port/HTTP/komut/web algılayıcılar koşullar tetiklendiğinde uyuyan oturumları uyandırır; sunucu geneli izleme tablosuyla «Sentinel» sekmesi kaydeder',

src/client/locales-vi.ts

@@ -17,6 +17,12 @@
 /** The vi dictionary (key-set-equal to zh, enforced by the type annotation in locales.ts). */
 export const vi: Record<string, string> = {
   files: 'Tệp',
+  guideDescFiles: 'Duyệt cây tệp của workspace; bấm để xem trước hoặc chỉnh sửa',
+  guideDescGit: 'Thay đổi Git và thay đổi tệp của phiên này trong một tab',
+  guideDescSubagent: 'Sơ đồ subagent và tác vụ nền, theo thời gian thực',
+  guideDescSidechat: 'Luồng hỏi tiếp độc lập kế thừa ngữ cảnh của phiên này',
+  guideDescTerminal: 'Shell thật (xterm + pty), tự kết nối lại',
+  guideDescBrowser: 'Trình duyệt nhúng, có thể mở link trong chat',
   changesSessionEmpty: 'Chưa có thao tác tệp nào trong phiên này',
   changesRead: 'Đọc',
   changesMdReading: 'Đọc',
@@ -100,6 +106,8 @@ export const vi: Record<string, string> = {
   terminalError: 'Kết nối terminal thất bại',
   terminalConnectFailed: 'Terminal kết nối thất bại nhiều lần',
   terminalRetry: 'Thử lại',
+  terminalWaitBanner: 'Agent đang chờ {needle}',
+  terminalSkipWait: 'Bỏ qua thời gian chờ',
   terminalDepsFailed: 'Dependency terminal node-pty tải thất bại',
   terminalDepsHint: 'Chạy lệnh sau trong terminal hoặc cmd trên máy DSH để sửa, rồi nhấn thử lại (node-pty đồng bộ phiên bản với lõi DSH):',
   terminalDepsProfile: ' (phát hiện profile: {profile})',
@@ -395,7 +403,7 @@ export const vi: Record<string, string> = {
   addPluginsViewerCardDesc: 'Đăng ký xem trước loại tệp mới',
   addPluginsTabDesc: 'Trang thanh bên (tab) có thể mở rộng qua plugin. Plugin đăng ký qua service ctx.betterSidebar; nhấp «Cài đặt» để sao chép lệnh cài, dán vào terminal nơi DSH chạy rồi thực thi.',
   addPluginsViewerDesc: 'Trình xem tệp có thể mở rộng qua plugin. Plugin đăng ký qua service ctx.betterSidebar; nhấp «Cài đặt» để sao chép lệnh cài, dán vào terminal nơi DSH chạy rồi thực thi.',
-  addPluginsBrowseMore: 'Duyệt thêm plugin trên GitHub (topic: dsh-better-sidebar)',
+  addPluginsBrowseMore: 'Duyệt thêm plugin trên GitHub (topic: dsh-apes-sidebar)',
   addPluginsSearch: 'Tìm theo tên / mô tả plugin…',
   addPluginsNoMatch: 'Không có plugin phù hợp',
   addPluginsRecommended: 'Plugin đề xuất',
@@ -408,7 +416,7 @@ export const vi: Record<string, string> = {
   pluginGithubWorkbenchDesc: 'Tab GitHub Workbench: cây repo từ xa + Issues / Pull requests / Actions với hỗ trợ ghi đầy đủ — tạo Issue/PR, bình luận, chỉnh sửa, đóng/mở lại, merge squash·merge·rebase (xác nhận mạnh), chạy lại/hủy CI; bộ chuyển repo tự liệt kê các repo có quyền truy cập và tìm kiếm repo công khai; khi chưa cài better-sidebar sẽ tự động chuyển sang panel bên phải độc lập',
   pluginMdExportDesc: 'Thêm nút «Xuất» vào thanh công cụ Markdown của better-sidebar: một cú nhấp chuyển .md hiện tại thành HTML độc lập (bảng/khối mã/sơ đồ Mermaid nhúng, bố cục theo theme xem trước) và lưu cạnh tệp .md, hoặc xuất PDF qua hộp thoại in',
   pluginCodeNavDesc: 'Điều hướng xem trước mã: tự nhận diện ngôn ngữ theo loại tệp và tô sáng cú pháp, phác thảo ký hiệu (lọc lớp/phương thức/biến + nhảy một cú nhấp), tìm kiếm trong tệp (tô sáng mọi kết quả, trước/sau, phân biệt hoa thường) — đảm nhận xem trước tệp mã trong trình soạn thảo better-sidebar',
-  pluginSuhuangScrollDesc: 'Kết nối Suhuang Scroll Runtime cục bộ với phần cài đặt DSH và better-sidebar để cấu hình mô hình, kiểm tra kết nối và điều khiển chấm bài liên tục; yêu cầu Suhuang Scroll Runtime và dsh-better-sidebar',
+  pluginSuhuangScrollDesc: 'Kết nối Suhuang Scroll Runtime cục bộ với phần cài đặt DSH và better-sidebar để cấu hình mô hình, kiểm tra kết nối và điều khiển chấm bài liên tục; yêu cầu Suhuang Scroll Runtime và dsh-apes-sidebar',
   pluginBetterOverleafDesc: 'Tab Overleaf cho better-sidebar: đăng nhập trực tiếp qua trình duyệt CDP (hỗ trợ Chromium bên thứ ba), danh sách/chuyển dự án, mirror git cục bộ trong <workspace>/overleaf/, đồng bộ git hai chiều với dự phòng API chỉ đọc, xem trước tệp qua workbench của thanh bên',
   pluginGitRemotesDesc: 'Tab Git Remotes của better-sidebar: xem branch/upstream/ahead-behind, fetch (có thể prune), pull ff-only, push chỉ sau khi xác nhận trong tab. Không thay thế tab stage/commit Git built-in, cũng không cung cấp force-push hay công cụ auto-push cho mô hình',
   pluginSentinelDesc: 'Hệ thống đánh thức agent theo điều kiện: cảm biến file/process/port/HTTP/command/webhook, khi điều kiện đạt sẽ tự đánh thức phiên ngủ; đăng ký tab «Sentinel» hiển thị bảng giám sát toàn server',

src/client/locales-zh-HK.ts

@@ -32,6 +32,12 @@
 /** The zh-HK dictionary (key-set-equal to zh, enforced by the type annotation in locales.ts). */
 export const zhHK: Record<string, string> = {
   files: '檔案',
+  guideDescFiles: '瀏覽工作區檔案樹，點開即可預覽或編輯',
+  guideDescGit: 'Git 變更與本輪檔案改動，雙視角合一',
+  guideDescSubagent: '子代理拓撲與背景任務，即時狀態',
+  guideDescSidechat: '繼承目前工作階段上下文的獨立追問執行緒',
+  guideDescTerminal: '真實 shell 終端（xterm + pty），斷線重連',
+  guideDescBrowser: '內嵌網頁瀏覽器，可接管聊天中的外鏈',
   changesSessionEmpty: '本工作階段還沒有檔案操作',
   changesRead: '讀取',
   changesMdReading: '閱讀',
@@ -115,6 +121,8 @@ export const zhHK: Record<string, string> = {
   terminalError: '終端連線失敗',
   terminalConnectFailed: '終端多次連線失敗',
   terminalRetry: '重試',
+  terminalWaitBanner: 'Agent 正在等待 {needle}',
+  terminalSkipWait: '跳過等待',
   terminalDepsFailed: '終端依賴 node-pty 載入失敗',
   terminalDepsHint: '在 DSH 所在環境的終端或 cmd 中執行以下命令修復，然後點重試（node-pty 與 DSH 核心保持同一版本）：',
   terminalDepsProfile: '（偵測到 profile：{profile}）',
@@ -410,7 +418,7 @@ export const zhHK: Record<string, string> = {
   addPluginsViewerCardDesc: '註冊新的檔案類型預覽',
   addPluginsTabDesc: '側邊欄頁面（Tab）可以由插件擴展。插件透過 ctx.betterSidebar 服務註冊；點擊「安裝」複製安裝命令，貼到 DSH 所在環境的終端執行。',
   addPluginsViewerDesc: '檔案預覽器可以由插件擴展。插件透過 ctx.betterSidebar 服務註冊；點擊「安裝」複製安裝命令，貼到 DSH 所在環境的終端執行。',
-  addPluginsBrowseMore: '在 GitHub 上瀏覽更多插件（topic: dsh-better-sidebar）',
+  addPluginsBrowseMore: '在 GitHub 上瀏覽更多插件（topic: dsh-apes-sidebar）',
   addPluginsSearch: '搜尋插件名稱 / 描述…',
   addPluginsNoMatch: '沒有匹配的插件',
   addPluginsRecommended: '推薦插件',
@@ -423,7 +431,7 @@ export const zhHK: Record<string, string> = {
   pluginGithubWorkbenchDesc: 'better-sidebar「GitHub 工作台」Tab：遠端儲存庫目錄樹 + Issues / Pull requests / Actions 頁簽，讀取之外支援新建 Issue/PR、評論、編輯、關閉重開、squash·merge·rebase 合併（強確認）與重跑/取消 CI；儲存庫彈出層自動拉取有權限列表並支援公開儲存庫搜尋；未安裝 better-sidebar 時自動降級為獨立右側面板',
   pluginMdExportDesc: '在 better-sidebar 的 Markdown 工具列上新增「匯出」按鈕：一鍵把目前 .md 渲染為獨立 HTML（表格/程式碼區塊/Mermaid 圖表內嵌，版面跟隨預覽主題）直接儲存到同目錄，或透過列印對話框匯出為 PDF',
   pluginCodeNavDesc: '程式碼預覽導覽：按檔案類型自動識別語言並高亮語法，符號大綱（類別/方法/變數篩選 + 一鍵跳轉），檔案內搜尋（全部符合高亮、上/下一處、區分大小寫），接管 better-sidebar 的程式碼檔案預覽',
-  pluginSuhuangScrollDesc: '把本機蘇黃共閱 Runtime 接入 DSH 設定與 better-sidebar，支援模型設定、連線測試及連續閱卷控制；使用前須安裝 Suhuang Scroll Runtime 與 dsh-better-sidebar',
+  pluginSuhuangScrollDesc: '把本機蘇黃共閱 Runtime 接入 DSH 設定與 better-sidebar，支援模型設定、連線測試及連續閱卷控制；使用前須安裝 Suhuang Scroll Runtime 與 dsh-apes-sidebar',
   pluginBetterOverleafDesc: 'better-sidebar 的 Overleaf 分頁：直連 CDP 瀏覽器登入（支援第三方 Chromium），專案列表/切換，<workspace>/overleaf/ 本地 git 映像，git 雙向同步（API 唯讀兜底），檔案預覽走側邊欄工作台',
   pluginGitRemotesDesc: 'better-sidebar Git 遠端 Tab：看分支/上游/ahead-behind，fetch（可 prune）、ff-only pull、確認後才 push。不替換內建 Git 的暫存/提交，也不提供 force-push 或模型自動推送',
   pluginSentinelDesc: '條件驅動的 agent 喚醒系統：檔案/程序/連接埠/HTTP/命令/webhook 感測器，條件達成自動喚醒休眠工作階段；註冊「哨兵」Tab 展示伺服器全域監控表',

src/client/locales-zh-MO.ts

@@ -32,6 +32,12 @@
 /** The zh-HK dictionary (key-set-equal to zh, enforced by the type annotation in locales.ts). */
 export const zhMO: Record<string, string> = {
   files: '檔案',
+  guideDescFiles: '瀏覽工作區檔案樹，點開即可預覽或編輯',
+  guideDescGit: 'Git 變更與本輪檔案改動，雙視角合一',
+  guideDescSubagent: '子代理拓撲與背景任務，即時狀態',
+  guideDescSidechat: '繼承目前工作階段上下文的獨立追問執行緒',
+  guideDescTerminal: '真實 shell 終端（xterm + pty），斷線重連',
+  guideDescBrowser: '內嵌網頁瀏覽器，可接管聊天中的外鏈',
   changesSessionEmpty: '本工作階段還沒有檔案操作',
   changesRead: '讀取',
   changesMdReading: '閱讀',
@@ -115,6 +121,8 @@ export const zhMO: Record<string, string> = {
   terminalError: '終端連線失敗',
   terminalConnectFailed: '終端多次連線失敗',
   terminalRetry: '重試',
+  terminalWaitBanner: 'Agent 正在等待 {needle}',
+  terminalSkipWait: '跳過等待',
   terminalDepsFailed: '終端依賴 node-pty 載入失敗',
   terminalDepsHint: '在 DSH 所在環境的終端或 cmd 中執行以下命令修復，然後點重試（node-pty 與 DSH 核心保持同一版本）：',
   terminalDepsProfile: '（偵測到 profile：{profile}）',
@@ -410,7 +418,7 @@ export const zhMO: Record<string, string> = {
   addPluginsViewerCardDesc: '註冊新的檔案類型預覽',
   addPluginsTabDesc: '側邊欄頁面（Tab）可以由插件擴展。插件透過 ctx.betterSidebar 服務註冊；點擊「安裝」複製安裝命令，貼到 DSH 所在環境的終端執行。',
   addPluginsViewerDesc: '檔案預覽器可以由插件擴展。插件透過 ctx.betterSidebar 服務註冊；點擊「安裝」複製安裝命令，貼到 DSH 所在環境的終端執行。',
-  addPluginsBrowseMore: '在 GitHub 上瀏覽更多插件（topic: dsh-better-sidebar）',
+  addPluginsBrowseMore: '在 GitHub 上瀏覽更多插件（topic: dsh-apes-sidebar）',
   addPluginsSearch: '搜尋插件名稱 / 描述…',
   addPluginsNoMatch: '沒有匹配的插件',
   addPluginsRecommended: '推薦插件',
@@ -423,7 +431,7 @@ export const zhMO: Record<string, string> = {
   pluginGithubWorkbenchDesc: 'better-sidebar「GitHub 工作台」Tab：遠端儲存庫目錄樹 + Issues / Pull requests / Actions 頁簽，讀取之外支援新建 Issue/PR、評論、編輯、關閉重開、squash·merge·rebase 合併（強確認）與重跑/取消 CI；儲存庫彈層自動拉取有權限清單並支援公開儲存庫搜尋；未安裝 better-sidebar 時自動降級為獨立右側面板',
   pluginMdExportDesc: '在 better-sidebar 的 Markdown 工具列上新增「匯出」按鈕：一鍵把目前 .md 渲染為獨立 HTML（表格/程式碼區塊/Mermaid 圖表內嵌，版面跟隨預覽主題）直接儲存到同目錄，或透過列印對話框匯出為 PDF',
   pluginCodeNavDesc: '程式碼預覽導覽：按檔案類型自動識別語言並高亮語法，符號大綱（類別/方法/變數篩選 + 一鍵跳轉），檔案內搜尋（全部符合高亮、上/下一處、區分大小寫），接管 better-sidebar 的程式碼檔案預覽',
-  pluginSuhuangScrollDesc: '把本機蘇黃共閱 Runtime 接入 DSH 設定與 better-sidebar，支援模型設定、連線測試及連續閱卷控制；使用前須安裝 Suhuang Scroll Runtime 與 dsh-better-sidebar',
+  pluginSuhuangScrollDesc: '把本機蘇黃共閱 Runtime 接入 DSH 設定與 better-sidebar，支援模型設定、連線測試及連續閱卷控制；使用前須安裝 Suhuang Scroll Runtime 與 dsh-apes-sidebar',
   pluginBetterOverleafDesc: 'better-sidebar 的 Overleaf 分頁：直連 CDP 瀏覽器登入（支援第三方 Chromium），專案列表/切換，<workspace>/overleaf/ 本地 git 映像，git 雙向同步（API 唯讀兜底），檔案預覽走側邊欄工作台',
   pluginGitRemotesDesc: 'better-sidebar Git 遠端 Tab：看分支/上游/ahead-behind，fetch（可 prune）、ff-only pull、確認後才 push。不替換內建 Git 的暫存/提交，也不提供 force-push 或模型自動推送',
   pluginSentinelDesc: '條件驅動的 agent 喚醒系統：檔案/程序/連接埠/HTTP/命令/webhook 感測器，條件達成自動喚醒休眠工作階段；註冊「哨兵」Tab 展示伺服器全域監控表',

src/client/locales-zh-TW.ts

@@ -32,6 +32,12 @@
 /** The zh-HK dictionary (key-set-equal to zh, enforced by the type annotation in locales.ts). */
 export const zhTW: Record<string, string> = {
   files: '檔案',
+  guideDescFiles: '瀏覽工作區檔案樹，點開即可預覽或編輯',
+  guideDescGit: 'Git 變更與本輪檔案改動，雙視角合一',
+  guideDescSubagent: '子代理拓撲與背景任務，即時狀態',
+  guideDescSidechat: '繼承目前工作階段上下文的獨立追問執行緒',
+  guideDescTerminal: '真實 shell 終端（xterm + pty），斷線重連',
+  guideDescBrowser: '內嵌網頁瀏覽器，可接管聊天中的外鏈',
   changesSessionEmpty: '本作業階段還沒有檔案操作',
   changesRead: '讀取',
   changesMdReading: '閱讀',
@@ -115,6 +121,8 @@ export const zhTW: Record<string, string> = {
   terminalError: '終端連線失敗',
   terminalConnectFailed: '終端多次連線失敗',
   terminalRetry: '重試',
+  terminalWaitBanner: 'Agent 正在等待 {needle}',
+  terminalSkipWait: '跳過等待',
   terminalDepsFailed: '終端依賴 node-pty 載入失敗',
   terminalDepsHint: '在 DSH 所在環境的終端或 cmd 中執行以下命令修復，然後點重試（node-pty 與 DSH 核心保持同一版本）：',
   terminalDepsProfile: '（偵測到 profile：{profile}）',
@@ -410,7 +418,7 @@ export const zhTW: Record<string, string> = {
   addPluginsViewerCardDesc: '註冊新的檔案類型預覽',
   addPluginsTabDesc: '側邊欄頁面（Tab）可以由插件擴展。插件透過 ctx.betterSidebar 服務註冊；點擊「安裝」複製安裝命令，貼到 DSH 所在環境的終端執行。',
   addPluginsViewerDesc: '檔案預覽器可以由插件擴展。插件透過 ctx.betterSidebar 服務註冊；點擊「安裝」複製安裝命令，貼到 DSH 所在環境的終端執行。',
-  addPluginsBrowseMore: '在 GitHub 上瀏覽更多插件（topic: dsh-better-sidebar）',
+  addPluginsBrowseMore: '在 GitHub 上瀏覽更多插件（topic: dsh-apes-sidebar）',
   addPluginsSearch: '搜尋插件名稱 / 描述…',
   addPluginsNoMatch: '沒有匹配的插件',
   addPluginsRecommended: '推薦插件',
@@ -423,7 +431,7 @@ export const zhTW: Record<string, string> = {
   pluginGithubWorkbenchDesc: 'better-sidebar「GitHub 工作台」Tab：遠端儲存庫目錄樹 + Issues / Pull requests / Actions 頁籤，讀取之外支援建立 Issue/PR、留言、編輯、關閉重開、squash·merge·rebase 合併（強確認）與重跑/取消 CI；儲存庫彈出視窗自動載入有權限清單並支援公開儲存庫搜尋；未安裝 better-sidebar 時自動降級為獨立右側面板',
   pluginMdExportDesc: '在 better-sidebar 的 Markdown 工具列上新增「匯出」按鈕：一鍵把目前 .md 渲染為獨立 HTML（表格/程式碼區塊/Mermaid 圖表內嵌，版面跟隨預覽主題）直接儲存到同目錄，或透過列印對話框匯出為 PDF',
   pluginCodeNavDesc: '程式碼預覽導覽：按檔案類型自動識別語言並高亮語法，符號大綱（類別/方法/變數篩選 + 一鍵跳轉），檔案內搜尋（全部符合高亮、上/下一處、區分大小寫），接管 better-sidebar 的程式碼檔案預覽',
-  pluginSuhuangScrollDesc: '把本機蘇黃共閱 Runtime 接入 DSH 設定與 better-sidebar，支援模型設定、連線測試及連續閱卷控制；使用前須安裝 Suhuang Scroll Runtime 與 dsh-better-sidebar',
+  pluginSuhuangScrollDesc: '把本機蘇黃共閱 Runtime 接入 DSH 設定與 better-sidebar，支援模型設定、連線測試及連續閱卷控制；使用前須安裝 Suhuang Scroll Runtime 與 dsh-apes-sidebar',
   pluginBetterOverleafDesc: 'better-sidebar 的 Overleaf 分頁：直連 CDP 瀏覽器登入（支援第三方 Chromium），專案列表/切換，<workspace>/overleaf/ 本地 git 映像，git 雙向同步（API 唯讀兜底），檔案預覽走側邊欄工作台',
   pluginGitRemotesDesc: 'better-sidebar Git 遠端 Tab：看分支/上游/ahead-behind，fetch（可 prune）、ff-only pull、確認後才 push。不替換內建 Git 的暫存/提交，也不提供 force-push 或模型自動推送',
   pluginSentinelDesc: '條件驅動的 agent 喚醒系統：檔案/程序/連接埠/HTTP/命令/webhook 感測器，條件達成自動喚醒休眠工作階段；註冊「哨兵」Tab 展示伺服器全域監控表',

src/client/locales.ts

@@ -24,6 +24,12 @@
 /** The zh dictionary (also registered into the DSH locale registry under {@link LOCALE_NS}). */
 export const zh = {
   files: '文件',
+  guideDescFiles: '浏览工作区文件树，点开即预览或编辑',
+  guideDescGit: 'Git 变更与本轮文件改动，双视角合一',
+  guideDescSubagent: '子代理拓扑与后台任务，实时状态',
+  guideDescSidechat: '继承当前会话上下文的独立追问线程',
+  guideDescTerminal: '真实 shell 终端（xterm + pty），断线重连',
+  guideDescBrowser: '内嵌网页浏览器，可接管聊天里的外链',
   changesSessionEmpty: '本会话还没有文件操作',
   changesRead: '读取',
   changesMdReading: '阅读',
@@ -112,6 +118,8 @@ export const zh = {
   terminalError: '终端连接失败',
   terminalConnectFailed: '终端多次连接失败',
   terminalRetry: '重试',
+  terminalWaitBanner: 'Agent 正在等待 {needle}',
+  terminalSkipWait: '跳过等待',
   terminalDepsFailed: '终端依赖 node-pty 加载失败',
   terminalDepsHint: '在 DSH 所在环境的终端或 cmd 中执行以下命令修复，然后点重试（node-pty 与 DSH 核心保持同一版本）：',
   terminalDepsProfile: '（检测到 profile：{profile}）',
@@ -407,7 +415,7 @@ export const zh = {
   addPluginsViewerCardDesc: '注册新的文件类型预览',
   addPluginsTabDesc: '侧边栏页面（Tab）可以由插件扩展。插件通过 ctx.betterSidebar 服务注册；点击「安装」复制安装命令，粘贴到 DSH 所在环境的终端执行。',
   addPluginsViewerDesc: '文件预览器可以由插件扩展。插件通过 ctx.betterSidebar 服务注册；点击「安装」复制安装命令，粘贴到 DSH 所在环境的终端执行。',
-  addPluginsBrowseMore: '在 GitHub 上浏览更多插件（topic: dsh-better-sidebar）',
+  addPluginsBrowseMore: '在 GitHub 上浏览更多插件（topic: dsh-apes-sidebar）',
   addPluginsSearch: '搜索插件名称 / 描述…',
   addPluginsNoMatch: '没有匹配的插件',
   addPluginsRecommended: '推荐插件',
@@ -419,7 +427,7 @@ export const zh = {
   pluginFlowglassDesc: '实时会话流程图：三列泳道展示用户、助手与工具调用，支持并行分组、子代理支线、逐层钻取和实时状态；安装 better-sidebar 后注册原生「流镜」Tab，未安装时保留独立抽屉',
   pluginGitForgeDesc: 'better-sidebar「Git 凭据」Tab：GitHub/Gitea 等 Forge 账号库 + 按项目授权 + push 策略硬拦；token 仅存本地 secrets，不进模型上下文；提供只读 GitForge 工具与 agent HTTPS credential helper',
   pluginGithubWorkbenchDesc: 'better-sidebar「GitHub 工作台」Tab：远端仓库目录树 + Issues / Pull requests / Actions 页签，读之外支持新建 Issue/PR、评论、编辑、关闭重开、squash·merge·rebase 合并（强确认）与重跑/取消 CI；仓库弹层自动拉取有权限列表并支持公开仓搜索；未装 better-sidebar 时自动降级为独立右侧面板',
-  pluginSuhuangScrollDesc: '把本地苏黄共阅 Runtime 接入 DSH 设置与 better-sidebar，支持模型配置、连接测试和连续阅卷控制；使用前需安装 Suhuang Scroll Runtime 与 dsh-better-sidebar',
+  pluginSuhuangScrollDesc: '把本地苏黄共阅 Runtime 接入 DSH 设置与 better-sidebar，支持模型配置、连接测试和连续阅卷控制；使用前需安装 Suhuang Scroll Runtime 与 dsh-apes-sidebar',
   pluginBetterOverleafDesc: 'better-sidebar 的 Overleaf 标签页：直连 CDP 浏览器登录（支持第三方 Chromium），项目列表/切换，<workspace>/overleaf/ 本地 git 镜像，git 双向同步（API 只读兜底），文件预览走侧边栏工作台',
   pluginGitRemotesDesc: 'better-sidebar Git 远程 Tab：看分支/上游/ahead-behind，fetch（可 prune）、ff-only pull、确认后才 push。不替换内置 Git 的暂存/提交，也不提供 force-push 或模型自动推送',
   pluginSentinelDesc: '条件驱动的 agent 唤醒系统：文件/进程/端口/HTTP/命令/webhook 传感器，条件达成自动唤醒休眠会话；注册「哨兵」Tab 展示服务器全局监控表',
@@ -458,6 +466,12 @@ export const zh = {
 /** The en dictionary (key-set-equal to zh, enforced by the type annotation). */
 export const en: Record<keyof typeof zh, string> = {
   files: 'Files',
+  guideDescFiles: 'Browse the workspace tree; click a file to preview or edit',
+  guideDescGit: 'Git changes and this session\'s file edits, in one tab',
+  guideDescSubagent: 'Subagent topology and background jobs, live',
+  guideDescSidechat: 'An independent follow-up thread inheriting this session\'s context',
+  guideDescTerminal: 'A real shell (xterm + pty) with reconnect',
+  guideDescBrowser: 'An embedded browser that can take over chat links',
   changesSessionEmpty: 'No file operations in this session yet',
   changesRead: 'Read',
   changesMdReading: 'Reading',
@@ -546,6 +560,8 @@ export const en: Record<keyof typeof zh, string> = {
   terminalError: 'Terminal connection failed',
   terminalConnectFailed: 'Terminal failed to connect repeatedly',
   terminalRetry: 'Retry',
+  terminalWaitBanner: 'Agent is waiting for {needle}',
+  terminalSkipWait: 'Skip wait',
   terminalDepsFailed: 'Terminal dependency node-pty failed to load',
   terminalDepsHint: 'Run the command below in a terminal or cmd on the DSH machine to repair it, then retry (node-pty stays in sync with the DSH core version):',
   terminalDepsProfile: ' (detected profile: {profile})',
@@ -841,7 +857,7 @@ export const en: Record<keyof typeof zh, string> = {
   addPluginsViewerCardDesc: 'Register a file-type preview',
   addPluginsTabDesc: 'Sidebar pages (tabs) can be extended by plugins. Plugins register through the ctx.betterSidebar service; clicking Install copies the install command — paste it into a terminal where your DSH profile lives and run it.',
   addPluginsViewerDesc: 'File previewers can be extended by plugins. Plugins register through the ctx.betterSidebar service; clicking Install copies the install command — paste it into a terminal where your DSH profile lives and run it.',
-  addPluginsBrowseMore: 'Browse more plugins on GitHub (topic: dsh-better-sidebar)',
+  addPluginsBrowseMore: 'Browse more plugins on GitHub (topic: dsh-apes-sidebar)',
   addPluginsSearch: 'Search by plugin name or description…',
   addPluginsNoMatch: 'No plugins match',
   addPluginsRecommended: 'Recommended plugins',
@@ -859,7 +875,7 @@ export const en: Record<keyof typeof zh, string> = {
   pluginSidebarQaDesc: 'Select-and-ask: Select conversation text → ask in the right-side panel → a dedicated follow-up session (❓追问) in the same workspace; a fast no-thinking model compresses the main context and injects it with the quote, without interrupting the main conversation. Follow-ups nest, continue, and archive',
   pluginSidenoteDesc: 'Codex-style side chat + selection annotations: fork the current session into a persistent side panel (archived out of the session list, multi-instance, /side command, survives reload, model follows the main session); select assistant text → numbered badge + note editor → an "N annotations" chip that rides your next message, or ask straight into a side chat',
   pluginSshTunnelDesc: 'SSH Tunnel tab: multi-host inventory + per-project grants + local secrets; SSHManager tool (exec/SFTP/session strategies); center interactive terminal and dual-pane SFTP',
-  pluginSuhuangScrollDesc: 'Connect the local Suhuang Scroll Runtime to DSH settings and better-sidebar for model configuration, connection tests, and continuous grading controls; requires Suhuang Scroll Runtime and dsh-better-sidebar',
+  pluginSuhuangScrollDesc: 'Connect the local Suhuang Scroll Runtime to DSH settings and better-sidebar for model configuration, connection tests, and continuous grading controls; requires Suhuang Scroll Runtime and dsh-apes-sidebar',
   pluginTurnReviewDesc: 'A human gate on the just-finished turn: Approve / Request changes per path with an optional comment; paths grouped by main session / subagent / unattributed; inline snapshot-vs-now diff before you decide. No fork, no /rewind',
   pluginVideoPreviewDesc: 'Inline video preview (.mp4/.webm/.mov/.mkv/.avi etc.) for the better-sidebar editor, backed by a dedicated /video host route with HTTP Range (206) support — scrubbing works and files are not capped by the 20MB mediaLimit',
   pluginCodeNavDesc: 'Code preview navigator: detects the language by file type and highlights syntax, symbol outline (class / method / variable filters + one-click jump), and in-file search (highlight all matches, prev/next, match case) — takes over code file preview in the better-sidebar editor',

src/client/native/index.ts

@@ -43,7 +43,7 @@ interface NativeTabRegistry {
     priority?: 'extension' | 'builtin' | 'fallback'
     canOpen?: (address: string) => boolean
     title: (address: string) => string
-    guide?: readonly { order: number; title: () => string; icon?: unknown }[]
+    guide?: readonly { order: number; title: () => string; description?: () => string; icon?: unknown }[]
   }): () => void
 }
 
@@ -55,7 +55,7 @@ const FILES_KIND = 'files'
 
 /** The plugin's implementation id for a descriptor (unique across kinds). */
 function nativeId(descriptorId: string): string {
-  return `dsh-better-sidebar:${descriptorId}`
+  return `dsh-apes-sidebar:${descriptorId}`
 }
 
 /** The descriptor's title text, evaluated fresh for the current locale. */
@@ -63,6 +63,21 @@ function titleOf(descriptor: TabDescriptor): string {
   return typeof descriptor.title === 'function' ? descriptor.title() : descriptor.title
 }
 
+/**
+ * The guide fields carrying the descriptor's own description line, evaluated
+ * fresh for the current locale. DSH 0.1.5-rc.1+ renders `description` only
+ * while the guide lists at most 4 entries, and a descriptor that declares
+ * none must reach the host with NO `description` field at all — the host has
+ * no fallback of its own, so an empty string would render as a blank second
+ * line rather than a clean title-only capsule.
+ * @param descriptor - the tab descriptor owning the guide entry.
+ * @returns the `description` field, or an empty object.
+ */
+function guideDescriptionOf(descriptor: TabDescriptor | undefined): { description?: () => string } {
+  const description = descriptor?.description
+  return description === undefined ? {} : { description: () => (typeof description === 'function' ? description() : description) }
+}
+
 /**
  * The guide row's glyph for a descriptor icon (nothing when it has none).
  * The native guide renders `entry.icon`, so a takeover registered without one
@@ -147,7 +162,7 @@ export function registerNativeSurface(deps: NativeSurfaceDeps): () => void {
       ctx.slots.inject('sidebar.right.pane.tab.title', () => ctx.slots.register({
         name: 'sidebar.right.pane.tab.title',
         key: id,
-        inject: () => ({ records }),
+        inject: () => ({ records, service, descriptorId: injected.descriptorId }),
       }, NativeTabTitle)),
     ]
 
@@ -181,6 +196,7 @@ export function registerNativeSurface(deps: NativeSurfaceDeps): () => void {
             guide: [{
               order: descriptor.order ?? 100,
               title: () => titleOf(descriptor),
+              ...guideDescriptionOf(descriptor),
               ...guideIconOf(icon),
             }],
           }),
@@ -198,7 +214,7 @@ export function registerNativeSurface(deps: NativeSurfaceDeps): () => void {
 
     /** One `files`-kind takeover: the plugin's explorer under the built-in kind. */
     const registerFilesKind = (editor: TabDescriptor | undefined): (() => void) => {
-      const id = 'dsh-better-sidebar:files'
+      const id = 'dsh-apes-sidebar:files'
       const disposeType = tabs.register({
         id,
         kind: FILES_KIND,
@@ -208,8 +224,9 @@ export function registerNativeSurface(deps: NativeSurfaceDeps): () => void {
           order: 10,
           title: () => t('files'),
           // The takeover IS the editor descriptor's page, so it carries the
-          // editor's glyph: without it the "Files" row is the only guide
-          // entry with an empty icon slot.
+          // editor's glyph AND guide line: without them the "Files" row is
+          // the only guide entry with a blank icon slot and no description.
+          ...guideDescriptionOf(editor),
           ...guideIconOf(editor?.icon),
         }],
       })

src/client/native/tab-adapter.tsx

@@ -31,6 +31,12 @@ import type { BetterSidebarService } from '../service.ts'
 import type { SidebarStore, SidebarTab, TabType } from '../state.ts'
 import css from '../sidebar.module.css'
 
+/** The chip glyph's size: the tab strip's own icon scale. */
+const CHIP_ICON_SIZE = 14
+
+/** The editor kind: a chip for a file row shows the file's own glyph. */
+const EDITOR_KIND = 'editor'
+
 /**
  * The plugin-side seed a native open carries in `navigation.params`.
  * JSON-shaped by convention (the native surface does not validate it).
@@ -285,7 +291,7 @@ export function NativeTabBody(props: NativeBodyInjected & NativeBodyFrameworkPro
     // it gets the same full-height box (its own root also relies on the
     // `flex: 1` contract the column host restores). The host div carries
     // `data-dsh-native-tab-host` (empty value) so the e2e lane can assert
-    // the fill, mirroring `data-dsh-better-sidebar`.
+    // the fill, mirroring `data-dsh-apes-sidebar`.
     return createElement(
       'div',
       { className: css.nativeTabHost, 'data-dsh-native-tab-host': '' },
@@ -330,20 +336,52 @@ export function NativeTabBody(props: NativeBodyInjected & NativeBodyFrameworkPro
 /** What a title registration injects. */
 export interface NativeTitleInjected {
   readonly records: NativeTabRecords
+  readonly service: BetterSidebarService
+  /** The descriptor id this title belongs to (one registration per descriptor). */
+  readonly descriptorId: string
 }
 
 /**
- * A live tab chip: the synthetic record's title (the editor rewrites it on an
- * in-place file switch, the side chat on the thread's first prompt). Without
- * this registration the chip would keep the title captured when the tab
- * opened.
+ * A live tab chip: the type's glyph followed by the synthetic record's title
+ * (the editor rewrites it on an in-place file switch, the side chat on the
+ * thread's first prompt). Without this registration the chip would keep the
+ * title captured when the tab opened.
+ *
+ * The host's tab definition has no icon field — a chip is drawn from the
+ * `title` text alone — but this slot IS the chip's content, so the glyph is
+ * ours to add. Placement follows the plugin's own semantics: an editor tab
+ * with a path shows that file's icon (the same glyph the tree row shows), and
+ * every other tab shows its descriptor's icon. Both ride
+ * `descriptor.icon`, so the workbench strip, the guide capsules and the chip
+ * cannot drift apart.
  */
 export function NativeTabTitle(props: NativeTitleInjected & NativeBodyFrameworkProps): ReactNode {
-  const { records, useTabInfo } = props
+  const { records, service, descriptorId, useTabInfo } = props
   const nativeTab = useTabInfo().tab
-  return useSyncExternalStore(
+  const version = useSyncExternalStore(
     listener => records.subscribe(listener),
-    () => records.get(nativeTab.id)?.tab.title ?? nativeTab.title,
+    () => records.versionOf(nativeTab.id),
+  )
+  const record = records.get(nativeTab.id)
+  const title = record?.tab.title ?? nativeTab.title
+  // `version` is read so a title/path/meta mutation re-renders the chip; the
+  // icon itself is derived from the record, never stored.
+  void version
+  const descriptor = service.getTab(descriptorId) ?? service.getTab(record?.tab.type ?? nativeTab.kind)
+  const path = record?.tab.path
+  const icon = path !== undefined && descriptorId === EDITOR_KIND
+    ? service.fileIcon(path, CHIP_ICON_SIZE)
+    : undefined
+  const glyph = icon ?? (typeof descriptor?.icon === 'function'
+    ? descriptor.icon(CHIP_ICON_SIZE)
+    : descriptor?.icon)
+  if (glyph === undefined || glyph === null) return title
+  return (
+    <>
+      {/* Decorative: the chip's accessible name stays the title. */}
+      <span className={css.chipIcon} aria-hidden="true">{glyph}</span>
+      {title}
+    </>
   )
 }
 

src/client/plugins-shared.ts

@@ -7,8 +7,8 @@
  * 文件预览 grids).
  */
 
-/** The GitHub topic page listing every repo tagged `dsh-better-sidebar`. */
-export const PLUGIN_TOPIC_URL = 'https://github.com/topics/dsh-better-sidebar'
+/** The GitHub topic page listing every repo tagged `dsh-apes-sidebar`. */
+export const PLUGIN_TOPIC_URL = 'https://github.com/topics/dsh-apes-sidebar'
 
 /** One curated plugin entry (name / url / description / install script). */
 export interface PluginEntry {

src/client/plugins-tabs.ts

@@ -31,25 +31,25 @@ export const builtinTabPlugins: readonly PluginEntry[] = [
     description: () => t('pluginEgoBrowserDesc'),
     // Registers a sidebar tab for the agent browser; optional peer of
     // better-sidebar (auto-tab when present, floating bubble when not).
-    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-better-sidebar && dsh plugin --profile web add git+https://github.com/Fisfzy/ego-browser.git',
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-apes-sidebar && dsh plugin --profile web add git+https://github.com/Fisfzy/ego-browser.git',
   },
   {
     id: 'dsh-better-overleaf',
     name: () => t('pluginBetterOverleafName'),
     url: 'https://github.com/Hoemr/dsh-better-overleaf',
     description: () => t('pluginBetterOverleafDesc'),
-    // Published on npm; peer-depends on dsh-better-sidebar (Overleaf tab),
+    // Published on npm; peer-depends on dsh-apes-sidebar (Overleaf tab),
     // so the install line installs the prerequisite first.
-    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-better-sidebar && dsh plugin --profile web add dsh-better-overleaf',
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-apes-sidebar && dsh plugin --profile web add dsh-better-overleaf',
   },
   {
     id: 'dsh-docs-panel',
     name: () => t('pluginDocsPanelName'),
     url: 'https://github.com/mlosun/dsh-docs-panel',
     description: () => t('pluginDocsPanelDesc'),
-    // dsh-docs-panel hard-depends on dsh-better-sidebar (required peer), so
+    // dsh-docs-panel hard-depends on dsh-apes-sidebar (required peer), so
     // the install line installs the prerequisite first, then the plugin.
-    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-better-sidebar && dsh plugin --profile web add dsh-docs-panel',
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-apes-sidebar && dsh plugin --profile web add dsh-docs-panel',
   },
   {
     id: 'dsh-flowglass',
@@ -58,23 +58,23 @@ export const builtinTabPlugins: readonly PluginEntry[] = [
     description: () => t('pluginFlowglassDesc'),
     // Flowglass keeps its standalone drawer as a fallback and registers the
     // native tab automatically when better-sidebar is present.
-    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-better-sidebar && dsh plugin --profile web add dsh-flowglass',
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-apes-sidebar && dsh plugin --profile web add dsh-flowglass',
   },
   {
     id: 'dsh-git-forge',
     name: () => t('pluginGitForgeName'),
     url: 'https://github.com/thirsty5034/dsh-git-forge',
     description: () => t('pluginGitForgeDesc'),
-    // Peer-depends on dsh-better-sidebar (Git Forge tab). Install the
+    // Peer-depends on dsh-apes-sidebar (Git Forge tab). Install the
     // prerequisite first; package is GitHub-sourced until npm publish.
-    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-better-sidebar && dsh plugin --profile web add "dsh-git-forge@github:thirsty5034/dsh-git-forge"',
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-apes-sidebar && dsh plugin --profile web add "dsh-git-forge@github:thirsty5034/dsh-git-forge"',
   },
   {
     id: 'dsh-git-remotes',
     name: () => t('pluginGitRemotesName'),
     url: 'https://github.com/yq04/dsh-git-remotes',
     description: () => t('pluginGitRemotesDesc'),
-    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-better-sidebar && dsh plugin --profile web add git+https://github.com/yq04/dsh-git-remotes.git',
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-apes-sidebar && dsh plugin --profile web add git+https://github.com/yq04/dsh-git-remotes.git',
   },
   {
     id: 'dsh-github-workbench',
@@ -91,18 +91,18 @@ export const builtinTabPlugins: readonly PluginEntry[] = [
     name: () => t('pluginSidebarQaName'),
     url: 'https://github.com/ChenRuoT/dsh-sidebar-qa',
     description: () => t('pluginSidebarQaDesc'),
-    // dsh-sidebar-qa hard-depends on dsh-better-sidebar (required peer), so
+    // dsh-sidebar-qa hard-depends on dsh-apes-sidebar (required peer), so
     // the install line installs the prerequisite first, then the plugin.
-    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-better-sidebar && dsh plugin --profile web add git+https://github.com/ChenRuoT/dsh-sidebar-qa.git',
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-apes-sidebar && dsh plugin --profile web add git+https://github.com/ChenRuoT/dsh-sidebar-qa.git',
   },
   {
     id: 'dsh-sidenote',
     name: () => t('pluginSidenoteName'),
     url: 'https://github.com/g-yixuan/dsh-sidenote',
     description: () => t('pluginSidenoteDesc'),
-    // dsh-sidenote hard-depends on dsh-better-sidebar (required peer), so
+    // dsh-sidenote hard-depends on dsh-apes-sidebar (required peer), so
     // the install line installs the prerequisite first, then the plugin.
-    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-better-sidebar && dsh plugin --profile web add dsh-sidenote',
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-apes-sidebar && dsh plugin --profile web add dsh-sidenote',
   },
   {
     id: 'dsh-server-deck',
@@ -112,7 +112,7 @@ export const builtinTabPlugins: readonly PluginEntry[] = [
     // Published on npm; dual-mount like flowglass — registers the native
     // "Servers" tab when better-sidebar is present, standalone drawer
     // otherwise. Install the prerequisite first.
-    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-better-sidebar && dsh plugin --profile web add dsh-server-deck@latest',
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-apes-sidebar && dsh plugin --profile web add dsh-server-deck@latest',
   },
   {
     id: 'dsh-suhuang-scroll',
@@ -121,24 +121,24 @@ export const builtinTabPlugins: readonly PluginEntry[] = [
     description: () => t('pluginSuhuangScrollDesc'),
     // Suhuang Scroll is a DSH Web plugin whose runtime console registers in
     // better-sidebar. Install the sidebar prerequisite before the npm package.
-    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-better-sidebar && dsh plugin --profile web add dsh-suhuang-scroll',
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-apes-sidebar && dsh plugin --profile web add dsh-suhuang-scroll',
   },
   {
     id: 'dsh-ssh-tunnel',
     name: () => t('pluginSshTunnelName'),
     url: 'https://github.com/thirsty5034/dsh-ssh-tunnel',
     description: () => t('pluginSshTunnelDesc'),
-    // Peer-depends on dsh-better-sidebar (SSH Tunnel tab + center terminal/SFTP).
+    // Peer-depends on dsh-apes-sidebar (SSH Tunnel tab + center terminal/SFTP).
     // Install the prerequisite first; package is GitHub-sourced until npm publish.
-    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-better-sidebar && dsh plugin --profile web add "dsh-ssh-tunnel@github:thirsty5034/dsh-ssh-tunnel"',
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-apes-sidebar && dsh plugin --profile web add "dsh-ssh-tunnel@github:thirsty5034/dsh-ssh-tunnel"',
   },
   {
     id: 'dsh-turn-review',
     name: () => t('pluginTurnReviewName'),
     url: 'https://github.com/yq04/dsh-turn-review',
     description: () => t('pluginTurnReviewDesc'),
-    // Needs dsh-better-sidebar (optional peer) for the tab; no model tools.
-    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-better-sidebar && dsh plugin --profile web add git+https://github.com/yq04/dsh-turn-review.git',
+    // Needs dsh-apes-sidebar (optional peer) for the tab; no model tools.
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-apes-sidebar && dsh plugin --profile web add git+https://github.com/yq04/dsh-turn-review.git',
   },
   {
     id: 'dsh-bilingual-reader',
@@ -148,6 +148,6 @@ export const builtinTabPlugins: readonly PluginEntry[] = [
     // Bilingual paper reading: a native-PDF tab with LLM selection translation,
     // isolated from the main conversation context. Hard-depends on the
     // better-sidebar tab service, so install the prerequisite first.
-    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-better-sidebar && dsh plugin --profile web add github:Johnblur/dsh-bilingual-reader',
+    install: 'cd ~/.dsh && dsh plugin --profile web add dsh-apes-sidebar && dsh plugin --profile web add github:Johnblur/dsh-bilingual-reader',
   },
 ]

src/client/service.ts

@@ -26,7 +26,8 @@ import {
   leafWithTab, openTabInBottomPane, patchTab, tabOpenIn,
   type SidebarSnapshot, type SidebarState, type SidebarStore, type SidebarTab, type TabType,
 } from './state.ts'
-import { extOf } from './paths.ts'
+import { baseName, extOf } from './paths.ts'
+import { builtinFileIcon, builtinFolderIcon } from './file-icons.tsx'
 import type { SessionScope } from './api.ts'
 import type { SidebarPrefs } from '../prefs-shared.ts'
 
@@ -162,6 +163,17 @@ export interface TabDescriptor {
   /** Unique id; also the `SidebarTab.type` value (`'explorer'`, `'my-plugin:db'`). */
   id: string
   title: string | (() => string)
+  /**
+   * One-line description of what this tab shows, rendered under the title in
+   * the host's new-tab list (DSH's native right Sidebar guide page). DSH
+   * 0.1.5-rc.1+ renders descriptions only while the guide lists at most 4
+   * entries — a longer list drops every description and shows titles alone —
+   * and a descriptor that declares none renders the title by itself (the
+   * host no longer substitutes a generic fallback, so declare the real
+   * purpose of the page). Evaluated at render time, so a function follows
+   * the active locale.
+   */
+  description?: string | (() => string)
   icon?: ReactNode | ((size: number) => ReactNode)
   /** + menu sort order (ascending); default 100. */
   order?: number
@@ -323,6 +335,62 @@ export interface FileViewerDescriptor {
   component: (props: FileViewerProps) => ReactNode
 }
 
+/**
+ * Describes one external file-icon registration (feature `fileIcons`).
+ * Registrations override the built-in per-extension glyph map for their
+ * extensions; unlike the built-ins (monochrome `currentColor` per the skin
+ * contract), a registration's icon may be ANY ReactNode — colored included —
+ * and the registering plugin owns how its colors behave across skins.
+ */
+export interface FileIconDescriptor {
+  /** Unique id (`'my-plugin:icons'`). */
+  id: string
+  /**
+   * Lowercase extensions without leading dot (`['csv','tsv']`). `[]` = the
+   * global default (catch-all): it only claims files the built-in glyph map
+   * does not cover — registered specifics and built-in glyphs always outrank
+   * it. OMITTED = no extension rule at all (a `names`-only registration is
+   * NOT a catch-all). Two values are RESERVED for directory rows (never
+   * matched against real file extensions): `'folder'` (a closed directory)
+   * and `'folder-open'` (an expanded directory) — see `FOLDER_EXT`.
+   */
+  exts?: readonly string[]
+  /**
+   * Exact FILE names (basename, case-insensitive — `['package.json',
+   * 'Dockerfile']`), the `fileNames` half of an icon theme. Name matches
+   * outrank extension matches, so a theme can color `package.json` apart
+   * from every other `.json`. Omitted/`[]` = no name rule.
+   */
+  names?: readonly string[]
+  /**
+   * Exact DIRECTORY names (basename, case-insensitive — `['node_modules',
+   * 'src']`), the `folderNames` half of an icon theme. A name match outranks
+   * the reserved `'folder'`/`'folder-open'` exts, and a descriptor with
+   * `folderNames` only claims the directories it names (never every folder —
+   * that is what the reserved exts are for). Omitted/`[]` = no name rule.
+   */
+  folderNames?: readonly string[]
+  /** Higher wins; default 0. Registered icons always outrank the built-in map. */
+  priority?: number
+  /**
+   * Size-aware icon factory (the tree and file tabs render at 14 today).
+   * `open` is the directory's expanded state for a DIRECTORY row and
+   * `undefined` for a file row — a folder icon uses it to pick between the
+   * closed and opened glyph.
+   */
+  icon: (path: string, size: number, open?: boolean) => ReactNode
+}
+
+/**
+ * Reserved `exts` values that claim DIRECTORY rows instead of file
+ * extensions: `'folder'` matches a closed directory, `'folder-open'` an
+ * expanded one (`folderIcon(path, open)` resolves them). They are filtered out of
+ * real-extension matching, so a file literally named `x.folder` is NOT
+ * claimed by a folder registration.
+ */
+export const FOLDER_EXT = 'folder' as const
+export const FOLDER_OPEN_EXT = 'folder-open' as const
+
 /** One `openTab` request. */
 export interface OpenTabSeed {
   type: string
@@ -397,8 +465,50 @@ export interface SidebarSurface {
 export interface BetterSidebarService {
   registerTab(descriptor: TabDescriptor): () => void
   registerFileViewer(descriptor: FileViewerDescriptor): () => void
+  registerFileIcon(descriptor: FileIconDescriptor): () => void
   getTabs(): readonly TabDescriptor[]
   getFileViewers(): readonly FileViewerDescriptor[]
+  getFileIcons(): readonly FileIconDescriptor[]
+  /**
+   * Find a SPECIFIC registered file icon for a path (priority desc, then
+   * registration order): a `names` match first, then an `exts` match.
+   * Catch-alls (`exts: []`) and folder registrations (`'folder'`/
+   * `'folder-open'`) are not consulted — this answers "did a registration
+   * claim this exact name or extension". Consumers should prefer
+   * `fileIcon`/`folderIcon`, which run the whole fallback chain.
+   */
+  matchFileIcon(path: string): FileIconDescriptor | undefined
+  /**
+   * Find the registered icon for DIRECTORY rows (priority desc, then
+   * registration order): a `folderNames` match on `name` first (pass the
+   * directory's basename), then the `'folder'`/`'folder-open'` reserved
+   * exts by `open`. Undefined = fall back to the built-in VSCodicons folder
+   * glyphs.
+   */
+  matchFolderIcon(open: boolean, name?: string): FileIconDescriptor | undefined
+  /**
+   * The authoritative FILE icon for a path (feature `fileIcons`), running
+   * the whole chain with per-factory crash isolation:
+   * 1. a specific registered name or extension (priority desc, registration
+   *    order),
+   * 2. the best registered global default (`exts: []`, priority desc) — an
+   *    external plugin that registers a catch-all owns every row the host's
+   *    classifier would otherwise draw,
+   * 3. the host's own `FileTypeIcon` artwork (feature `fileIcons`, DSH's
+   *    classifier and glyphs — the plugin ships no extension table).
+   * A throwing factory is logged (console.error) and skipped — the caller
+   * always gets a valid ReactNode.
+   */
+  fileIcon(path: string, size: number): ReactNode
+  /**
+   * The authoritative DIRECTORY icon for a tree row: the registered
+   * `folderNames`/`'folder'`/`'folder-open'` icon (priority desc), else the
+   * built-in `VscFolder`/`VscFolderOpened`. `path` is the directory's own
+   * path (a theme may vary icons per directory); `open` reaches the factory
+   * so one descriptor can render both states. Same crash isolation as
+   * `fileIcon`.
+   */
+  folderIcon(path: string, open: boolean, size: number): ReactNode
   /** Find a tab descriptor by id (undefined if not registered). */
   getTab(id: string): TabDescriptor | undefined
   /**
@@ -506,7 +616,7 @@ export function matchUrlTarget(tabs: readonly TabDescriptor[], url: URL): TabDes
     try {
       claimed = tab.urlTarget(url) === true
     } catch (error) {
-      console.error('[dsh-better-sidebar] urlTarget error:', error)
+      console.error('[dsh-apes-sidebar] urlTarget error:', error)
       continue
     }
     if (claimed) return tab
@@ -518,7 +628,7 @@ export function matchUrlTarget(tabs: readonly TabDescriptor[], url: URL): TabDes
  * The plugin version this service instance reports. Keep in lockstep with
  * `package.json`'s version — `tests/service.spec.ts` asserts the pair.
  */
-export const SIDEBAR_SERVICE_VERSION = '0.19.0-alpha.1'
+export const SIDEBAR_SERVICE_VERSION = '1.2.0'
 
 /**
  * Monotonic capability list consumers use to gate new API usage (features
@@ -533,6 +643,10 @@ export const SIDEBAR_SERVICE_VERSION = '0.19.0-alpha.1'
  * - 'pluginSettings': SidebarSettingsDeclaration.pluginToggles/render
  * - 'urlTarget' (v0.13.0): TabDescriptor.urlTarget (external-link claims)
  * - 'settingSelect': SidebarSettingToggle type 'select' (options/multi)
+ * - 'fileIcons' (v0.19.0): registerFileIcon/getFileIcons/matchFileIcon —
+ *   external file-tree icons overriding the built-in glyphs, matched by
+ *   extension (`exts`), exact file name (`names`), or directory name
+ *   (`folderNames`).
  *
  * v0.19.0 REMOVED 'floatWindows': the free-window feature is gone (DSH 0.1.5
  * owns the right column, so the plugin keeps only its bottom workbench).
@@ -549,6 +663,7 @@ export const SIDEBAR_FEATURES = [
   'pluginSettings',
   'urlTarget',
   'settingSelect',
+  'fileIcons',
 ] as const
 
 /** Run one plugin callback; a throw is logged and never breaks the caller. */
@@ -556,7 +671,7 @@ function safeCall(fn: () => void): void {
   try {
     fn()
   } catch (error) {
-    console.error('[dsh-better-sidebar] plugin callback error:', error)
+    console.error('[dsh-apes-sidebar] plugin callback error:', error)
   }
 }
 
@@ -568,6 +683,7 @@ function safeCall(fn: () => void): void {
 export function createBetterSidebarService(store: SidebarStore): BetterSidebarService {
   const tabs = new Map<string, TabDescriptor>()
   const viewers = new Map<string, FileViewerDescriptor>()
+  const fileIcons = new Map<string, FileIconDescriptor>()
   const listeners = new Set<() => void>()
   /** The native right-Sidebar write face, installed by the client half. */
   let surface: SidebarSurface | undefined
@@ -583,7 +699,7 @@ export function createBetterSidebarService(store: SidebarStore): BetterSidebarSe
 
   const registerTab = (descriptor: TabDescriptor): (() => void) => {
     if (tabs.has(descriptor.id)) {
-      throw new Error(`[dsh-better-sidebar] tab type "${descriptor.id}" already registered`)
+      throw new Error(`[dsh-apes-sidebar] tab type "${descriptor.id}" already registered`)
     }
     tabs.set(descriptor.id, descriptor)
     notify()
@@ -597,7 +713,7 @@ export function createBetterSidebarService(store: SidebarStore): BetterSidebarSe
 
   const registerFileViewer = (descriptor: FileViewerDescriptor): (() => void) => {
     if (viewers.has(descriptor.id)) {
-      throw new Error(`[dsh-better-sidebar] file viewer "${descriptor.id}" already registered`)
+      throw new Error(`[dsh-apes-sidebar] file viewer "${descriptor.id}" already registered`)
     }
     viewers.set(descriptor.id, descriptor)
     notify()
@@ -611,8 +727,112 @@ export function createBetterSidebarService(store: SidebarStore): BetterSidebarSe
 
   const getTabs = (): readonly TabDescriptor[] => Array.from(tabs.values())
   const getFileViewers = (): readonly FileViewerDescriptor[] => Array.from(viewers.values())
+  const getFileIcons = (): readonly FileIconDescriptor[] => Array.from(fileIcons.values())
   const getTab = (id: string): TabDescriptor | undefined => tabs.get(id)
 
+  const registerFileIcon = (descriptor: FileIconDescriptor): (() => void) => {
+    if (fileIcons.has(descriptor.id)) {
+      throw new Error(`[dsh-apes-sidebar] file icons "${descriptor.id}" already registered`)
+    }
+    fileIcons.set(descriptor.id, descriptor)
+    notify()
+    return () => {
+      if (fileIcons.get(descriptor.id) === descriptor) {
+        fileIcons.delete(descriptor.id)
+        notify()
+      }
+    }
+  }
+
+  // Registrations in ranking order: priority desc, stable for equal
+  // priorities (insertion order) — the same ranking `matchFileViewer` uses.
+  const rankedFileIcons = (): FileIconDescriptor[] =>
+    Array.from(fileIcons.values()).sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
+
+  // Specific registrations only: catch-alls (`exts: []`) and folder
+  // registrations (`'folder'`/`'folder-open'`) are skipped, and the reserved
+  // folder values never match a real file's extension. Name rules (`names`)
+  // outrank extension rules. The built-in glyph map is not consulted here —
+  // an undefined result IS the "fall through" signal the `fileIcon` resolver
+  // acts on.
+  const matchFileIcon = (path: string): FileIconDescriptor | undefined => {
+    const ext = extOf(path)
+    // Reserved folder values never claim a real file: `x.folder` falls
+    // through to the built-in/catch-all chain like any unknown extension.
+    const reserved = ext === FOLDER_EXT || ext === FOLDER_OPEN_EXT
+    const name = baseName(path).toLowerCase()
+    const ranked = rankedFileIcons()
+    for (const d of ranked) {
+      if (d.names?.some(entry => entry.toLowerCase() === name) === true) return d
+    }
+    if (reserved) return undefined
+    for (const d of ranked) {
+      if (d.exts?.includes(ext) === true) return d
+    }
+    return undefined
+  }
+
+  // Directory rows: a `folderNames` match on the directory's own basename
+  // first, then the reserved `'folder'`/`'folder-open'` exts (a catch-all
+  // never claims a directory).
+  const matchFolderIcon = (open: boolean, name?: string): FileIconDescriptor | undefined => {
+    const ranked = rankedFileIcons()
+    if (name !== undefined) {
+      const wanted = name.toLowerCase()
+      for (const d of ranked) {
+        if (d.folderNames?.some(entry => entry.toLowerCase() === wanted) === true) return d
+      }
+    }
+    const want = open ? FOLDER_OPEN_EXT : FOLDER_EXT
+    for (const d of ranked) {
+      if (d.exts?.includes(want) === true) return d
+    }
+    return undefined
+  }
+
+  /** Run one registered factory; a throw is logged and returns undefined. */
+  const safeIcon = (d: FileIconDescriptor, path: string, size: number, open?: boolean): ReactNode => {
+    try {
+      return d.icon(path, size, open)
+    } catch (error) {
+      console.error(`[dsh-apes-sidebar] file icon factory "${d.id}" error:`, error)
+      return undefined
+    }
+  }
+
+  // The authoritative file-icon chain (see the interface doc): specific name
+  // or extension registration → registered catch-all → the host's own
+  // file-type artwork. The catch-all ranks by priority desc then registration
+  // order (first wins), which is what lets an external plugin own "every
+  // extension I did not name" without also owning the ones DSH draws.
+  const fileIcon = (path: string, size: number): ReactNode => {
+    const specific = matchFileIcon(path)
+    if (specific !== undefined) {
+      const icon = safeIcon(specific, path, size)
+      if (icon !== undefined) return icon
+    }
+    for (const d of rankedFileIcons()) {
+      if (d.exts !== undefined && d.exts.length === 0) {
+        const icon = safeIcon(d, path, size)
+        if (icon !== undefined) return icon
+      }
+    }
+    return builtinFileIcon(path, size)
+  }
+
+  // Directory rows: registered folderNames/folder/folder-open icon, else the
+  // host's folder glyph. The row's path feeds the factory (a registration may
+  // vary icons per directory) and `open` lets one descriptor render both
+  // states.
+  const folderIcon = (path: string, open: boolean, size: number): ReactNode => {
+    const registered = matchFolderIcon(open, baseName(path))
+    if (registered !== undefined) {
+      const icon = safeIcon(registered, path, size, open)
+      if (icon !== undefined) return icon
+    }
+    return builtinFolderIcon(open, size)
+  }
+
   // The enable switches come from the user's side card prefs (the shared
   // store the service is bound to): an absent key means enabled.
   const isTabEnabled = (id: string): boolean => store.getPrefs().tabsEnabled[id] !== false
@@ -653,7 +873,7 @@ export function createBetterSidebarService(store: SidebarStore): BetterSidebarSe
     // + menu nor from derived flows (file opens, subagent auto-open,
     // external plugins). Already-open tabs keep rendering.
     if (!isTabEnabled(seed.type)) {
-      console.warn(`[dsh-better-sidebar] tab type "${seed.type}" is disabled in the side card settings`)
+      console.warn(`[dsh-apes-sidebar] tab type "${seed.type}" is disabled in the side card settings`)
       return
     }
     const descriptor = tabs.get(seed.type)
@@ -896,8 +1116,14 @@ export function createBetterSidebarService(store: SidebarStore): BetterSidebarSe
   return {
     registerTab,
     registerFileViewer,
+    registerFileIcon,
     getTabs,
     getFileViewers,
+    getFileIcons,
+    matchFileIcon,
+    matchFolderIcon,
+    fileIcon,
+    folderIcon,
     getTab,
     isTabEnabled,
     isViewerEnabled,

src/client/settings-nav-icon.ts

@@ -10,7 +10,7 @@
  * disposal, so the adaptation remains HMR-safe.
  */
 
-export const SETTINGS_NAV_MARKER = 'data-dsh-better-sidebar-settings-nav'
+export const SETTINGS_NAV_MARKER = 'data-dsh-apes-sidebar-settings-nav'
 
 /**
  * Keep the marker on the settings-nav button whose visible text is this

src/client/sidebar.module.css

@@ -420,6 +420,17 @@ body[data-dsh-sidebar-dragging] .bottomPanel {
   overflow: hidden;
 }
 
+/* The native tab chip's glyph (drawn by the plugin inside the host's
+   `sidebar.right.pane.tab.title` slot, which is the chip's content): sized to
+   the text, aligned on its baseline box, and separated from the title the way
+   the workbench strip separates its own glyph from its label. */
+.chipIcon {
+  display: inline-flex;
+  align-items: center;
+  margin-right: 6px;
+  flex: none;
+}
+
 /* One tab's mounted content; inactive tabs stay mounted but hidden so
    switching never tears down terminals/editors (state survives). */
 .paneTab {
@@ -1895,6 +1906,28 @@ body[data-dsh-sidebar-dragging] .bottomPanel {
   opacity: 0.85;
 }
 
+/* The "Agent 正在等待 {needle}" wait banner: a warn-toned strip above the
+   terminal surface while the model blocks in terminal_wait_for; the needle
+   ellipsizes inline and the full text rides the title tooltip. */
+.terminalWaitBanner {
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 3px 10px;
+  font: var(--dsw-font-xxxs-11);
+  color: var(--dsw-alias-state-warn-label);
+  background: var(--dsw-alias-state-warn-tertiary);
+}
+
+.terminalWaitNeedle {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
 .boundaryError {
   position: fixed;
   right: 0;
@@ -2014,7 +2047,7 @@ body[data-dsh-sidebar-dragging] .bottomPanel {
    restores the `flex: 1` semantics our tab roots rely on, and gives
    third-party descriptors' components the same box inside the native pane.
    The wrapper div carries `data-dsh-native-tab-host` so the e2e lane can
-   assert the fill (mirroring `data-dsh-better-sidebar`). */
+   assert the fill (mirroring `data-dsh-apes-sidebar`). */
 .nativeTabHost {
   display: flex;
   flex-direction: column;

src/client/sidebar/bottom-toggle.tsx

@@ -22,8 +22,8 @@ import { BottomDockToggle } from '../Sidebar.tsx'
 export function registerBottomToggle(ctx: Context, store: SidebarStore): () => void {
   return ctx.slots.inject('conversation.session.header.utilities', () => ctx.slots.register({
     name: 'conversation.session.header.utilities',
-    id: 'dsh-better-sidebar:bottom-toggle',
+    id: 'dsh-apes-sidebar:bottom-toggle',
     order: 10,
-    registrant: 'dsh-better-sidebar',
+    registrant: 'dsh-apes-sidebar',
   }, () => <BottomDockToggle store={store} />))
 }

src/client/sidebar/use-host-feeds.ts

@@ -7,7 +7,8 @@
  */
 import { useEffect, useRef } from 'react'
 import type { Context, SidebarSessionList } from '../../context-types.ts'
-import { reconcileAgentTerminals, type SidebarStore } from '../state.ts'
+import { mirrorAgentWaits, reconcileAgentTerminals, type SidebarStore } from '../state.ts'
+import { isNarrowWidth } from '../breakpoints.ts'
 import { detectNewDirectSubagent } from '../subagent-detect.ts'
 import { detectNewJob } from '../subagent-jobs.ts'
 import { t } from '../locales.ts'
@@ -26,6 +27,55 @@ const FAILURE_LIMIT = 3
  */
 const AUTO_OPEN_DEBOUNCE_MS = 500
 
+/**
+ * The native column's public face, as this module reaches it. Both actions
+ * act on the session whose surface is MOUNTED (the controller reads its
+ * binding), which is why the park below is gated on the target session being
+ * the on-screen one.
+ */
+interface NativeColumnFace {
+  isExpanded?: () => boolean
+  toggleExpanded?: () => void
+}
+
+/**
+ * Activate the Tasks page (the `subagent` tab type) in DSH's native right
+ * Sidebar — the landing the two auto-open switches promise: the right column
+ * IS the sidebar the user means, while the plugin's own bottom workbench only
+ * serves its own flows (its `+` menu and the first-expansion terminal). Every
+ * other open in this plugin already lands there, so a `target: 'bottom'` here
+ * puts the Tasks page in the bottom bar instead.
+ *
+ * A background activation must not take over a narrow viewport: below 768px
+ * the host draws that column FULLSCREEN, so the tab is placed and the column
+ * is put back to collapsed — parked, waiting behind the expand control,
+ * instead of covering the chat. The host expands on every open
+ * (`openContent` plans `setExpanded(true)`) and offers no option to suppress
+ * it, hence the read-then-restore pair: both commits land in one React batch,
+ * so the column never renders the intermediate state. The viewport is read
+ * when the activation FIRES (the debounced subagent trigger included), so a
+ * resize while arming is honoured.
+ *
+ * @param ctx - the client context (`ctx.sidebarRight` + `ctx.betterSidebar`).
+ * @param sessionId - the session the feed reports the activity for.
+ * @param options.background - `true` for background activity (parks on narrow
+ *   viewports); `false` for the explicit topology jump-back, which is a user
+ *   gesture and always leaves the column as the host expanded it.
+ */
+function activateTasksPage(ctx: Context, sessionId: string, options: { background: boolean }): void {
+  const column = ctx.get('sidebarRight') as unknown as NativeColumnFace | undefined
+  const park = options.background
+    // The face acts on the MOUNTED session: parking is only meaningful (and
+    // only safe) when the activation targets the one on screen.
+    && ctx.sessions.list.getSnapshot().current === sessionId
+    && isNarrowWidth(window.innerWidth)
+    // Only a column the user had COLLAPSED is put back: an expanded one is in
+    // use, and closing it under the user would be worse than the takeover.
+    && column?.isExpanded?.() === false
+  ctx.get('betterSidebar')?.openTab({ type: 'subagent', title: t('subagent') })
+  if (park) column?.toggleExpanded?.()
+}
+
 export function useHostFeeds(feeds: {
   ctx: Context
   store: SidebarStore
@@ -44,8 +94,9 @@ export function useHostFeeds(feeds: {
    * the same shell without losing the agent's work — capped like the
    * terminal view's own reconnect loop, so a refused endpoint never spins
    * forever (the next session switch restarts the loop).
-   * While the terminal tab type is disabled in settings, pushes are
-   * ignored (no auto-added tabs); re-enabling makes the next push converge.
+   * While the terminal tab type is disabled in settings, pushes add / remove
+   * no tabs — but the authoritative wait map is STILL mirrored (see the
+   * branch below); re-enabling makes the next push converge on both.
    */
   useEffect(() => {
     if (sessionId === undefined) return
@@ -62,10 +113,15 @@ export function useHostFeeds(feeds: {
       socket.onmessage = (event) => {
         if (typeof event.data !== 'string') return
         try {
-          const list = JSON.parse(event.data) as Array<{ uuid: string; title: string; command: string; exited: boolean }>
+          const list = JSON.parse(event.data) as Array<{ uuid: string; title: string; command: string; exited: boolean; waiting?: { needle: string; since: number } | null }>
           if (!Array.isArray(list)) return
           store.reduce(s => ctx.get('betterSidebar')?.isTabEnabled('terminal') === false
-            ? s
+            // Terminal tabs are disabled: skip tab add/remove reconciliation,
+            // but STILL mirror the authoritative wait map — a wait resolving
+            // during the disabled window must clear its banner state, or a
+            // re-enabled terminal keeps a stale banner until the next
+            // unrelated push.
+            ? mirrorAgentWaits(s, list)
             : reconcileAgentTerminals(s, list))
         } catch {
           // Malformed push: ignore (the next push will reconcile).
@@ -75,7 +131,7 @@ export function useHostFeeds(feeds: {
         if (closed) return
         failures += 1
         if (failures >= FAILURE_LIMIT) {
-          console.error('[dsh-better-sidebar] agent-terminals connection failed; stopping reconnect loop', sessionId)
+          console.error('[dsh-apes-sidebar] agent-terminals connection failed; stopping reconnect loop', sessionId)
           return
         }
         retry = window.setTimeout(connect, 2000)
@@ -147,7 +203,7 @@ export function useHostFeeds(feeds: {
         if (closed) return
         failures += 1
         if (failures >= FAILURE_LIMIT) {
-          console.error('[dsh-better-sidebar] agent-opens connection failed; stopping reconnect loop', sessionId)
+          console.error('[dsh-apes-sidebar] agent-opens connection failed; stopping reconnect loop', sessionId)
           return
         }
         retry = window.setTimeout(connect, 2000)
@@ -166,11 +222,11 @@ export function useHostFeeds(feeds: {
    * Subagent auto-activation: the moment the current conversation spawns its
    * FIRST direct subagent (a 0 → N transition on the list feed), the "auto
    * open" pref is on, and the Tasks tab type is enabled in settings, activate
-   * the Tasks page. Single-instance semantics focus an existing pane tab in
-   * place or raise an existing free window; a new tab lands in the right pane
-   * and is never duplicated. On wide viewports the right panel also expands;
-   * on narrow viewports background activity never forces the full-screen
-   * drawer open over the chat.
+   * the Tasks page in DSH's native right Sidebar. Single-instance semantics
+   * focus an existing tab in place; a new tab lands in that column and is
+   * never duplicated. Landing it EXPANDS the column on wide viewports, while
+   * a narrow viewport (where the host draws that column fullscreen) parks the
+   * tab instead of taking the screen over — see {@link activateTasksPage}.
    * Switching to a session that already has subagents never triggers — its
    * baseline starts at the current count — so a deliberate layout is never
    * fought.
@@ -196,7 +252,7 @@ export function useHostFeeds(feeds: {
       if (!detectNewDirectSubagent(baseline, ctx.sessions.list.getSnapshot(), sessionId)) return
       if (!store.getPrefs().autoOpenSubagent) return
       if (ctx.get('betterSidebar')?.isTabEnabled('subagent') === false) return
-      ctx.get('betterSidebar')?.openTab({ type: 'subagent', title: t('subagent'), target: 'bottom' })
+      activateTasksPage(ctx, sessionId, { background: true })
     }, AUTO_OPEN_DEBOUNCE_MS)
     autoOpenPendingRef.current = { baseline, timer }
   }, [sessionList, sessionId, store, ctx])
@@ -212,11 +268,12 @@ export function useHostFeeds(feeds: {
    * Job auto-activation: the moment a NEW background job appears for the
    * current conversation (a job id the previous snapshot lacked), the
    * auto-open pref is on, and the Tasks tab type is enabled, activate the Tasks
-   * page that contains the background-jobs section. The right panel expands
-   * only on wide viewports. Unlike the subagent trigger (0 → N only), ANY
-   * new job id triggers: the agent may start several jobs in one session, and
-   * each should surface. A fresh page load never triggers — its baseline starts
-   * at the current snapshot.
+   * page that contains the background-jobs section — in DSH's native right
+   * Sidebar, expanded on wide viewports and parked on narrow ones exactly like
+   * the subagent trigger ({@link activateTasksPage}). Unlike that trigger
+   * (0 → N only), ANY new job id triggers: the agent may start several jobs in
+   * one session, and each should surface. A fresh page load never triggers —
+   * its baseline starts at the current snapshot.
    */
   const jobBaselineRef = useRef<SidebarSessionList | undefined>(undefined)
   useEffect(() => {
@@ -226,7 +283,7 @@ export function useHostFeeds(feeds: {
     if (!detectNewJob(prev, sessionList, sessionId)) return
     if (!store.getPrefs().autoOpenJobs) return
     if (ctx.get('betterSidebar')?.isTabEnabled('subagent') === false) return
-    ctx.get('betterSidebar')?.openTab({ type: 'subagent', title: t('subagent'), target: 'bottom' })
+    activateTasksPage(ctx, sessionId, { background: true })
   }, [sessionList, sessionId, store, ctx])
 
   /**
@@ -235,17 +292,18 @@ export function useHostFeeds(feeds: {
    * session's OWN layout (a fresh child session defaults to the explorer).
    * The README contract says the Subagent page must stay open with the jumped
    * node highlighted — so once the current session becomes the recorded jump
-   * target, re-open the Subagent page on top of the child's layout (expanding
-   * the panel first if it is collapsed). Only this explicit node click arms
-   * the flag, so switching to a subagent session by any other means keeps
-   * that session's own layout untouched.
+   * target, re-open the Tasks page on top of the child's layout, in DSH's
+   * native right Sidebar. This one is an explicit user gesture, so it always
+   * takes the host's expansion (no narrow-viewport parking). Only this node
+   * click arms the flag, so switching to a subagent session by any other means
+   * keeps that session's own layout untouched.
    */
   const subagentJumpRef = useRef<string | undefined>(undefined)
   useEffect(() => {
     const pending = subagentJumpRef.current
     if (pending === undefined || sessionId !== pending) return
     subagentJumpRef.current = undefined
-    ctx.get('betterSidebar')?.openTab({ type: 'subagent', title: t('subagent'), target: 'bottom' })
+    activateTasksPage(ctx, sessionId, { background: false })
   }, [sessionId, store, ctx])
 
   return { subagentJumpRef }

src/client/state.ts

@@ -91,6 +91,14 @@ export interface SidebarState {
   bottomOpenedOnce: boolean
   /** The bottom workbench's split tree. */
   bottomSplits: SplitNode
+  /**
+   * Live agent-terminal wait state (uuid → the wait the model currently
+   * blocks on in `terminal_wait_for`), mirrored from the host's
+   * agent-terminals push. Transient by design: sanitizeState never restores
+   * it, so a reload starts clean and the next push (sent immediately on WS
+   * attach) repopulates it.
+   */
+  agentWaits: Record<string, { needle: string; since: number }>
 }
 
 export const TAB_MAX_WIDTH = 160
@@ -167,6 +175,7 @@ export function makeDefaultState(): SidebarState {
     bottomHeight: BOTTOM_DEFAULT,
     bottomOpenedOnce: false,
     bottomSplits: bottomLeaf,
+    agentWaits: {},
   }
 }
 
@@ -661,6 +670,36 @@ export function agentTabId(uuid: string): string {
   return `${AGENT_TAB_PREFIX}${uuid}`
 }
 
+/** Shallow equality of two agent-wait maps (same keys, same needle+since). */
+function sameAgentWaits(
+  a: SidebarState['agentWaits'] | undefined,
+  b: Record<string, { needle: string; since: number }>,
+): boolean {
+  if (a === undefined) return Object.keys(b).length === 0
+  const aKeys = Object.keys(a)
+  if (aKeys.length !== Object.keys(b).length) return false
+  for (const key of aKeys) {
+    const av = a[key]
+    const bv = b[key]
+    if (av === undefined || bv === undefined) return false
+    if (av.needle !== bv.needle || av.since !== bv.since) return false
+  }
+  return true
+}
+
+/** Fold the pushed terminal snapshots into the authoritative wait map. */
+function serverWaitsOf(
+  agentTerminals: ReadonlyArray<{ uuid: string; title: string; waiting?: { needle: string; since: number } | null }>,
+): Record<string, { needle: string; since: number }> {
+  const serverWaits: Record<string, { needle: string; since: number }> = {}
+  for (const terminal of agentTerminals) {
+    if (terminal.waiting !== undefined && terminal.waiting !== null) {
+      serverWaits[terminal.uuid] = { needle: terminal.waiting.needle, since: terminal.waiting.since }
+    }
+  }
+  return serverWaits
+}
+
 /**
  * Reconcile the sidebar's agent-terminal tabs with the host's live list.
  * The host pushes the current list of agent terminals (created by the model
@@ -675,7 +714,7 @@ export function agentTabId(uuid: string): string {
  */
 export function reconcileAgentTerminals(
   state: SidebarState,
-  agentTerminals: ReadonlyArray<{ uuid: string; title: string }>,
+  agentTerminals: ReadonlyArray<{ uuid: string; title: string; waiting?: { needle: string; since: number } | null }>,
 ): SidebarState {
   const existingTabs = allLeaves(state.bottomSplits).flatMap(leaf => leaf.tabs)
   const existingAgentTabs = existingTabs.filter(tab => isAgentTabId(tab.id))
@@ -689,7 +728,12 @@ export function reconcileAgentTerminals(
   // convergence: no title suffix, no meta write — the tab keeps its uuid
   // so a later reconcile push revives it if the agent reopens the same one).
   const toRemove = existingAgentTabs.filter(tab => !serverUuids.has(agentUuidOf(tab.id)) && tab.pin === undefined)
-  if (toAdd.length === 0 && toRemove.length === 0) return state
+  // Mirror the live wait state from the push (authoritative: a vanished
+  // waiting field simply drops the entry). A waits-only change must still
+  // produce a new state — the tab add/remove no-change check alone would
+  // swallow banner updates.
+  const serverWaits = serverWaitsOf(agentTerminals)
+  if (toAdd.length === 0 && toRemove.length === 0 && sameAgentWaits(state.agentWaits, serverWaits)) return state
   // Remove tabs whose uuids vanished from the server list (the agent closed
   // them, or the pty exited and was reaped). Reuse closeTab's leaf cleanup.
   let bottomSplits = state.bottomSplits
@@ -711,7 +755,24 @@ export function reconcileAgentTerminals(
     }
     next = openTabInBottomPane(next, tab)
   }
-  return next
+  return { ...next, agentWaits: serverWaits }
+}
+
+/**
+ * Mirror ONLY the authoritative agent-wait map from a push — no tab
+ * add/remove reconciliation. Used while the `terminal` tab type is disabled:
+ * the tab surface is frozen, but a wait that resolves during that window
+ * must still clear its banner state, or a re-enabled terminal keeps a stale
+ * banner/⏳ until some unrelated host event fires the next full reconcile.
+ * Idempotent: a no-op when the map already matches.
+ */
+export function mirrorAgentWaits(
+  state: SidebarState,
+  agentTerminals: ReadonlyArray<{ uuid: string; title: string; waiting?: { needle: string; since: number } | null }>,
+): SidebarState {
+  const serverWaits = serverWaitsOf(agentTerminals)
+  if (sameAgentWaits(state.agentWaits, serverWaits)) return state
+  return { ...state, agentWaits: serverWaits }
 }
 
 // ── The per-session store ──────────────────────────────────────────────────
@@ -849,6 +910,9 @@ export function sanitizeState(parsed: unknown): SidebarState | undefined {
     // auto-terminal exactly once after the upgrade.
     bottomOpenedOnce: record.bottomOpenedOnce === true,
     bottomSplits,
+    // The agent wait state is TRANSIENT (like revealed): never restored from
+    // storage — the host's first push after attach repopulates it.
+    agentWaits: {},
   }
 }
 

src/config.ts

@@ -2,7 +2,7 @@
  * Serializable configuration and defaults for the sidebar host half. Loader
  * schema validation normally fills defaults; {@link resolveSidebarConfig}
  * applies the same defaults for direct callers that bypass the Loader.
- * @module dsh-better-sidebar/config
+ * @module dsh-apes-sidebar/config
  */
 
 import z from 'schemastery'

src/context-types.ts

@@ -572,14 +572,14 @@ export interface SidebarContextShape {
 /**
  * The Context this plugin sees: the vendored cordis Context intersected with
  * the structural service faces above. Re-exported from the package root so a
- * consumer can `import type { Context } from 'dsh-better-sidebar'`.
+ * consumer can `import type { Context } from 'dsh-apes-sidebar'`.
  */
 export type Context = CordisContext & SidebarContextShape
 
 /**
  * Consumer-facing augmentation (deliberately the only one kept): a plugin
  * that imports `Context` from `@deepseek-ai/cordis` and does
- * `import type {} from 'dsh-better-sidebar'` sees `ctx.betterSidebar`
+ * `import type {} from 'dsh-apes-sidebar'` sees `ctx.betterSidebar`
  * without importing this package's own Context type.
  */
 declare module '@deepseek-ai/cordis' {