dsh-zen-remote 2.3.11 → 2.4.0

package/CHANGELOG.md

@@ -5,131 +5,92 @@
 [GitHub Releases](https://github.com/KyoMio/dsh-zen-remote/releases)（tag 驱动自动生成）。
 界面半边的细节叙事另见 [`docs/interface.md`](docs/interface.md) 的「更新日志」一节。
 
+## 2.4.0（2026-11-09）
+
+### 新增
+
+- **无头服务器命令行工具 `dsh-zen-remote`**：支持在终端完成三步配置向导（`setup`）、设备配对与二维码展示、公网入口管理与连通自检，以及查看状态与导出脱敏诊断报告。
+- **子客户端多服务端同时连接（最多 8 台）**：子客户端现在可同时配对并连接最多 8 台主服务端，侧边栏远程分组按配对顺序合并（同名服务端自动编号），插件页向导与设置卡支持逐台管理与状态查看。
+- **会话通知总开关与来源会话名**（[#55](https://github.com/KyoMio/dsh-zen-remote/issues/55)）：新增 `pushEnabled` 一键停用全部自动推送与 `push_notify` 工具，以及 `pushSessionName` 在推送正文首行显示来源会话名。
+- **主进程状态文件合并**：将本机服务端 ID、共享会话表与已配对服务端列表统一收口到 `~/.dsh/zen-remote-state.json`，启动时自动迁移旧状态文件。
+
+### 修复
+
+- **修复 DSH 0.2.2+ 下远程会话终端报「此功能暂不支持远程会话」**：适配 DSH 0.2.2 新的 `terminal/attach` 双工终端通道并兼容 `dsh-better-sidebar` 0.30.1，远程会话终端可正常打开与输入。
+- **远程会话正文图片无法显示**（[#55](https://github.com/KyoMio/dsh-zen-remote/issues/55)）：子客户端查看远程会话时，回复正文与文档预览中的本地图片现在会自动转发到对应主服务端读取，不再因本机无该路径而显示破图。
+- **PWA 通知小图标显示为实心方块**（[#55](https://github.com/KyoMio/dsh-zen-remote/issues/55)）：将通知状态栏小图标换为透明底单色剪影，避免在系统状态栏与任务栏被渲染成实心色块。
+
 ## 2.3.11（2026-11-06）
 
 ### 修复
 
-- **修复冷启动竞态导致「会话与插件同步：异常」**（[#53](https://github.com/KyoMio/dsh-zen-remote/issues/53)）：
-  DSH 0.2.1-alpha.3 起网关调用必须自带 Peer，而客户端同步拦截的安装只等网关服务——
-  宿主的 connection 服务经另一层注入、可能显著滞后（插件多、启动慢的机器上尤甚）。
-  自检在 Peer 缺位时以 `reading 'signal'` 失败并按策略卸载拦截，此后无恢复路径，
-  表现为远程会话同步失效、需手动重载插件。现在安装声明等待 connection 服务，
-  服务到齐才安装并自检；0.1.7 / Electron 组合本就无此安装路径，行为不变。
+- **修复冷启动竞态导致「会话与插件同步：异常」**（[#53](https://github.com/KyoMio/dsh-zen-remote/issues/53)）：等待宿主 `connection` 服务就绪后再安装客户端同步拦截并执行自检，避免启动较慢时自检失败导致远程会话同步失效。
 
 ## 2.3.10（2026-11-06）
 
 ### 修复
 
-- **适配 DSH 0.2.2-rc.1 移动端会话页空屏与首页设置按钮失灵**：DSH 0.2.2-rc.1 的
-  `AppFrame` 给主栏显式设置 `grid-area: 1/2`（落入移动端单列网格的 `0px` 第 2 列导致进入
-  会话一片空白），并在 `< 768px` 新增 `[data-sidebar-mask]`（作为首个子元素挤掉原先
-  `:first-child` 侧栏选择器）、`[data-shell-leading]` 左上角悬浮按钮与侧栏 `inert` /
-  `visibility: hidden`。现将主栏显式钉回第 1 列（`grid-area: 1 / 1`）、按稳定类名后缀
-  `[class$="_sidebarCol"]` 匹配侧栏并隐藏宿主遮罩与左上角悬浮按钮，同时在手机壳下剥离侧栏
-  `inert` 属性，恢复会话页正常渲染及首页设置按钮、底部芯片代点。
+- **适配 DSH 0.2.2-rc.1 移动端会话页空屏与首页设置按钮失灵**：修复 DSH 0.2.2-rc.1 网格列调整与新增遮罩导致的手机端进入会话空白、侧栏及首页设置按钮无法点击的问题。
 
 ## 2.3.9（2026-11-05）
 
 ### 新增
 
-- **适配 `dsh-better-sidebar` 0.30.0**：适配器新增 `/sidebar/sidechat-image` 旁聊图片路由适配，
-  并为多图载荷设置转发上限，旧版侧边栏插件的行为不受影响。
-- **手机端新建会话先定工作区（UX-3）**：点「+ 新建会话」直接进无工作区空会话时，
-  手机端此前会卡在英雄区 inert 的「选择工作区」状态。现在点下 FAB 先做决定：
-  已选工作区直接开；零或一个工作区直接用唯一值（无工作区的宿主保持原样可用）；
-  多个工作区且未选时，FAB 先弹出与标题栏一致的工作区底部抽屉，选好才开始会话。
-  工作区切换瞬间（建会话 → `replaceMain` 重挂载）输入栏短暂锁定置灰
-  （上限 1.5s 自动解锁），防止消息落在旧空会话上被重挂载抹掉、界面弹回占位态。
-- **首次激活子客户端后自动重载页面（UX-1）**：页面三条常驻全局流在加载时打开，
-  后端的流拦截器要等插件行重载后才装上——已打开的流不被包装，服务端的远程会话
-  从此进不了侧边栏。现在首次配对或保存把角色切到 client 后，等待
-  `client/status` 就绪（最多 3 秒）即自动重载；已是 client 的重新配对、写盘未落、
-  旧服务端（无诊断应答）都保持不重载。
+- **适配 `dsh-better-sidebar` 0.30.0**：支持远程会话转发旁聊图片路由 `/sidebar/sidechat-image`。
+- **手机端新建会话先定工作区**：多工作区未选定状态下点「+ 新建会话」先弹出工作区选择抽屉，防止卡在空会话占位页或切换瞬间丢消息。
+- **首次激活子客户端后自动重载页面**：首次配对或切换为子客户端角色后自动刷新页面，让侧边栏远程分组立即生效。
 
 ### 修复
 
-- **手机端任务/子代理弹出层点错位（UX-2）**：活动胶囊的触发器选择器此前先命中
-  面包屑的父会话切换器（同为 tree 弹层、文档序更靠前），胶囊上盖的是错误按钮；
-  弹出层也不再跟随胶囊位置。现在按类名后缀精确锁定目录触发器，并把触发器及其
-  锚点容器（同步 `z-index: 3` 层叠上下文）钉在活动胶囊的固定视口矩形上，弹出层
-  即随胶囊出现；同时固定左上角返回按钮在智能体团队按钮左侧并隐去后者文字标签。
-- **手机端右侧栏初始引导页纵向滚动**：当注册的侧边栏标签页变多超出屏幕高度时，
-  宿主引导页（`[data-sidebar-right-guide]`）此前因居中溢出与外层 `overflow: hidden`
-  裁切导致排在前面的入口无法看到或点击，现支持完整上下滚动。
+- **手机端任务/子代理弹出层点错位**：修复会话顶栏活动胶囊误触父会话切换器及弹层位置偏移的问题。
+- **手机端右侧栏初始引导页纵向滚动**：修复右侧栏标签较多超出屏幕高度时无法上下滚动查看的问题。
 
 ## 2.3.8（2026-11-03）
 
 ### 兼容
 
-- **DSH 0.2.2-alpha.3**：`session/control` 的实时 `projection` 帧改为按事件批量
-  （`seq` + `changes[{key, val}]`，取代逐键的 `key` / `value`）。子客户端合并远程
-  控制流时两种形态都能读，并统一拆成「逐键字段 + 单条 `changes`」的双形态帧，
-  本机 DSH 新旧版本都能直接应用（本机与服务端版本不一致时会话标题、模型选择等
-  投影不再停更或打断控制流）；服务端补发的投影帧同样改为双形态。
-- 插件清单声明 `dsh.manifestVersion: 1` 与 `engines.dsh: ">=0.2.1-alpha.2 <0.3.0-0"`
-  （含预发布：覆盖 npm latest 0.2.1-rc.5 与 alpha 通道 0.2.2-alpha.3）。
+- **适配 DSH 0.2.2-alpha.3**：兼容批量格式的实时会话状态投影帧，跨版本连接时会话标题与模型选择等状态正常同步。
+- **更新插件版本声明**：声明 `dsh.manifestVersion: 1` 与 `engines.dsh: ">=0.2.1-alpha.2 <0.3.0-0"`。
 
 ## 2.3.7（2026-11-02）
 
 ### 新增
 
-- **远程附件守卫扩展到回形针与粘贴**（issue #49）：此前只有拖拽会把「带子客户端
-  本机路径的非图片文件」从宿主的零拷贝捷径里拦下、改走字节上传，现在回形针选择器
-  与编辑器粘贴同样命中；拖入 / 粘贴**文件夹**时整批拦下并提示；附带 fetch-route
-  懒装重试与卸载守卫。
-- **导出诊断信息**：插件设置区块底部一键下载 `zen-remote-debug-<role>-<时间戳>.json`
-  （版本与角色 / 配置形态 / 诊断聚合 / host 另含网关摘要 / 近 300 条插件事件），
-  两层脱敏（配置按字段名挑选 + 统一脱敏器），可直接附到 GitHub issue；
-  经网关打开时拒绝导出，报告只能在本机生成。
+- **远程附件上传扩展到回形针与粘贴**（[#49](https://github.com/KyoMio/dsh-zen-remote/issues/49)）：子客户端远程会话中通过回形针选择或粘贴本机非图片文件时自动转为字节上传到服务端，并在拖入或粘贴文件夹时明确提示不支持。
+- **导出诊断信息**：插件设置页底部支持一键下载脱敏诊断 JSON，便于排查问题与附到 GitHub issue。
 
 ### 修复
 
-- **宽幅平板独立 PWA 顶部安全区**（≥1024px：iPad 横屏、12.9/13 吋 iPad 竖屏恰为
-  1024、安卓平板）：网关对所有非 desktop 设备注入 `viewport-fit=cover`，但安全区
-  补偿止步于 1023px 断点，顶部控件被压进状态栏、难以点按。新增
-  `(min-width: 1024px) and (display-mode: standalone)` 双门控规则补齐上下两个安全区
-  （锚定官方 AppFrame，`border-box` + `--mnav-sat`/`--mnav-sab`）；桌面浏览器与
-  桌面 App 构造性 no-op，≥1024px 桌面逐像素不变的硬约束不受影响。
-- **平板 PWA 整页可拖动弹回**：壳级 `overscroll-behavior` 此前只写在 body 且仅
-  纵轴，视口级橡皮筋在 768px 以上仍然活着。现 html/body 双写、双向杀掉；
-  内部滚动区不受影响，只是边缘滚动不再链到整页。
+- **宽幅平板独立 PWA 顶部安全区**：补齐 ≥1024px 独立 PWA 模式下的上下安全区内边距，避免顶部按钮被状态栏遮挡。
+- **平板 PWA 整页拖动回弹**：禁用视口级橡皮筋回弹，避免边缘滑动时整页跟着晃动。
 
 ## 2.3.6（2026-10-31）
 
-- 插件桥：支持 json-body WebSocket 帧的会话 id 定位与改写（`/sidebar/ws/sidechat`）。
-- 中继：观察 `agent/created` 的父会话，同步未通告的 sidechat / 子代理摘要。
-- 手机端：turn-tail 的 24h 时钟不再折行；信息卡合并 turns / steps 计数并显示 tok/s 速度。
+- 插件桥：支持 `/sidebar/ws/sidechat` 旁聊 WebSocket 的会话定位与转发。
+- 中继：同步新建子代理与旁聊会话的实时运行状态。
+- 手机端：修复对话尾部 24h 时间折行，信息卡合并轮次/步数并新增 `tok/s` 输出速度。
 
 ## 2.3.5（2026-10-30）
 
-- turn-fold：纯签名推理步不再留下空行（适配 DSH 0.2.1-rc.5）。
-- 安全与维护：新增 SECURITY.md 与 Dependabot（`@deepseek-ai/*` 闭包手动管理）、
-  测试以 `vm` 替代 `eval`；中继背压用例改为按余量驻留，修掉 CI 上的两连假失败。
+- 折叠：修复 DSH 0.2.1-rc.5 下纯签名推理步留下空行的问题。
+- 维护：新增 `SECURITY.md` 与 Dependabot 配置，优化测试稳定性。
 
 ## 2.3.4（2026-10-28）
 
-- 插件桥 v2 声明补全（PB-22 ~ PB-25）：`deny` 路由对一切远程上下文统一 503 拒答；
-  `rewriteIds` 新增创建型 `{ fields }` 声明，深扫改写范围扩到「请求自带 ∪ 已知会话
-  清单」；路径段 / json-body 定位路由进入协作校验链（逐命中共享校验、请求体体积
-  上限、隧道升级前置校验）。
+- 插件桥 v2：支持 `deny` 路由拒答、`rewriteIds` 响应会话 ID 改写，以及路径段与 JSON 体的会话定位校验。
 
 ## 2.3.3（2026-10-27）
 
-- 适配 dsh-better-sidebar 0.28.2；接受 DSH 0.2.2-alpha peer 并钉该版本的会话指纹。
+- 适配 `dsh-better-sidebar` 0.28.2，并支持 DSH 0.2.2-alpha 版本接口指纹。
 
 ## 2.3.2（2026-10-26）
 
-- 发版重跑，无代码变化（仅版本号与 README 徽章）。
+- 发版流程重跑，仅更新版本号与文档徽章。
 
 ## 2.3.1（2026-10-26）
 
-- 配置向导：三步配置向导上线（README 安装 / 向导快速上手重排并配截图）；Caddy
-  预编译发行版与国内镜像自动探测、cloudflared / Caddy 的连接与停滞超时、模式切换
-  停进程与状态清理；CI 每日预编译 Caddy + cloudflared 全平台产物并自动跟踪上游。
-- 安全：网关在 `0.0.0.0` 上拒绝未反代的公网 IP 直连；Caddy / Tunnel 模式把 host
-  重置回 `127.0.0.1`。
-- Windows：修复 Caddy 裸二进制下载、Cloudflare Tunnel UUID CNAME 校验、向导保存
-  CF token 前先切回 host 角色、重命名回退，以及网关 spawn 时绕开 `node.cmd`
-  批处理包装。
+- 配置向导：上线三步配置向导，支持内置 Caddy 自动证书与 Cloudflare Tunnel 一键拉起（含国内镜像加速）。
+- 安全：网关监听 `0.0.0.0` 时拒绝公网 IP 未反代直连，Caddy / Tunnel 模式自动切回 `127.0.0.1`。
+- Windows：修复 Caddy / Tunnel 向导配置与网关子进程启动兼容问题。
 
 更早版本（≤ 2.2.9）见 [GitHub Releases](https://github.com/KyoMio/dsh-zen-remote/releases)。

package/README.md

@@ -1,5 +1,5 @@
 <h1 align="center">dsh-zen-remote</h1>
-<p align="center">One DeepSeek Harness plugin, two roles. The <b>host</b> turns DSH into a phone-reachable PWA (mobile UI, pairing gateway, lock-screen push) and shares chosen sessions to paired desktops. The <b>client</b> runs inside another DSH desktop app and puts the host's shared sessions right into its own sidebar — full history, live progress, messages, approvals, terminal, everything executes on the host.</p>
+<p align="center">One DeepSeek Harness plugin, two roles. The <b>host</b> turns DSH into a phone-reachable PWA (mobile UI, pairing gateway, lock-screen push) and shares chosen sessions to paired desktops. The <b>client</b> runs inside another DSH desktop app and puts the host's shared sessions right into its own sidebar (up to <b>8 hosts</b> connected simultaneously) — full history, live progress, messages, approvals, terminal, everything executes on the host.</p>
 
 <p align="center">
 <a href="https://www.npmjs.com/package/dsh-zen-remote"><img src="https://img.shields.io/npm/v/dsh-zen-remote?style=flat-square&color=5B4CF0&logo=npm&label=npm" alt="npm version"></a>
@@ -21,7 +21,7 @@
 | ![Session list home](assets/home.png) | ![Session page](assets/session.png) | ![Session info card](assets/info.png) |
 
 | Composer permission sheet | Pairing page a public visitor sees |
-| --- | --- |
+| --- | --- | --- |
 | ![Composer permission sheet](assets/sheet.png) | ![Pairing page](assets/pairing.png) |
 
 > Screenshots are a 390×844 phone viewport in the light theme; both themes are supported. The pairing page is drawn by the gateway in DSH's official style, following the system light / dark appearance.
@@ -33,7 +33,7 @@
 1. [Install](#1-install)
 2. [Quick Start (Unified Setup & Pairing Wizard)](#2-quick-start-unified-setup--pairing-wizard)
    - [Scenario A: Set up as Host (Phone & Desktop Access)](#scenario-a-set-up-as-host-phone--desktop-access)
-   - [Scenario B: Set up another computer as Desktop Client](#scenario-b-set-up-another-computer-as-desktop-client)
+   - [Scenario B: Set up as Desktop Client (Connect up to 8 Hosts)](#scenario-b-set-up-as-desktop-client-connect-up-to-8-hosts)
 3. [Daily Usage: Session Sharing & Cross-Device Workflow](#3-daily-usage-session-sharing--cross-device-workflow)
 4. [Lock-Screen Push: When Notifications Fire](#4-lock-screen-push-when-notifications-fire)
 5. [Features](#5-features)
@@ -52,11 +52,44 @@ Open the **Plugins** page in the DSH sidebar → click **Add plugin** → type `
 
 ```sh
 dsh plugin --profile web add dsh-zen-remote
-# then restart dsh web
+# then restart dsh web (or run `npx dsh-zen-remote setup` to install, start, and configure in one go)
 ```
 
 > `dsh plugin` requires `--profile` to name the target profile. The desktop app's `desktop` profile is managed exclusively by the app (`--profile desktop` is refused on the CLI), so use the UI install above on the desktop app.
 
+### Headless Server CLI Wizard (`dsh-zen-remote`)
+
+The plugin ships a bundled CLI tool so remote VPS / headless servers (`dsh web`) can complete the entire setup, ingress configuration, three-light verification, and QR / desktop pairing flow in a terminal without opening a browser:
+
+```sh
+npx dsh-zen-remote setup        # 3-step interactive wizard: role → ingress → verify + terminal QR & desktop pairing
+dsh-zen-remote status           # current role, gateway & connection state (--json; --debug exports redacted diagnostics)
+```
+
+<details>
+<summary>Expand full CLI subcommand reference (<code>host</code> / <code>client</code> / non-interactive flags)</summary>
+
+```sh
+# Host commands (when role is host)
+dsh-zen-remote host device pair --device-role web              # mint a phone/browser pairing code + terminal QR (or desktop-client)
+dsh-zen-remote host device list                                # list paired devices (--json supported)
+dsh-zen-remote host device revoke <id|--all> [--yes]           # revoke one or all paired devices
+dsh-zen-remote host ingress start --mode lan                   # configure & start ingress (caddy | cloudflared | external | lan)
+dsh-zen-remote host ingress stop [--yes]                       # stop managed Caddy / Cloudflare Tunnel processes
+dsh-zen-remote host ingress verify [--no-wait]                 # three-light check + mint web QR & desktop pairing codes
+dsh-zen-remote host ingress snippet [--proxy nginx|caddy|lucky] # print reverse-proxy config snippets
+
+# Client commands (when role is client, up to 8 paired hosts)
+dsh-zen-remote client pair http://192.168.1.2:3088 --code 12345678 [--name My-Mac]
+dsh-zen-remote client list                                     # list all paired hosts (up to 8) and connection states
+dsh-zen-remote client unpair <hostUrl|entryId|--all> [--yes]   # remove one or all paired hosts
+```
+
+- **Preflight & non-interactive automation**: `setup` automatically scans candidate profiles for multi-select plugin installation (`desktop` is skipped) and launches the DSH daemon / app before starting the wizard. Pass `--yes` with the required flags (e.g. `setup --role host --ingress lan --no-wait --yes`) for unattended scripts.
+- **Architecture**: the CLI communicates with the running plugin over a `0600` local IPC socket (`~/.dsh/zen-remote-cli.sock`); Caddy and `cloudflared` stay managed by the plugin process. Use `--lang zh|en` to switch output language.
+
+</details>
+
 <details>
 <summary>Manual Profile Edit / Local Development (<code>link:</code>), Upgrading & Uninstall</summary>
 
@@ -66,7 +99,7 @@ dsh plugin --profile web add dsh-zen-remote
 // ~/.dsh/profiles/desktop/package.json
 {
   "dependencies": {
-    "dsh-zen-remote": "^2.3.11"        // for local development: "link:/path/to/dsh-zen-remote"
+    "dsh-zen-remote": "^2.4.0"        // for local development: "link:/path/to/dsh-zen-remote"
   }
 }
 ```
@@ -80,7 +113,7 @@ cd ~/.dsh/profiles/desktop && pnpm install
 - **Upgrading with HMR on**: remove `dsh-zen-remote` first, then install the new version (`dsh plugin --profile <name> remove dsh-zen-remote` → `add dsh-zen-remote`, or Uninstall → Add in the Plugins page).
 - **DSH 0.2.1-alpha.3+ profile reset**: `dsh --profile <name> --from-default-profile <template>` replaces an existing custom profile with a fresh copy; back up `~/.dsh/profiles/<name>` first.
 - **Upgrading from 1.x**: since 2.0.0 the composition layer is a single row (`dsh-zen-remote`). Remove any legacy `dsh-zen-remote-gateway`, `dsh-zen-remote-push`, or manual `dsh-push.mjs` lines from `cordis.patch.yml`. Existing `~/.dsh/lan-gate.config.json` settings and paired devices carry over automatically.
-- **Uninstalling**: click **Uninstall** on the `dsh-zen-remote` plugin page and restart. To also wipe pairing and share state, delete `~/.dsh/lan-gate-state.json`, `~/.dsh/lan-gate.config.json`, `~/.dsh/zen-remote-shares.json`, and `~/.dsh/zen-remote-server.json`.
+- **Uninstalling**: click **Uninstall** on the `dsh-zen-remote` plugin page and restart. To also wipe pairing and share state, delete `~/.dsh/lan-gate-state.json`, `~/.dsh/lan-gate.config.json`, and `~/.dsh/zen-remote-state.json` (older versions also kept `~/.dsh/zen-remote-shares.json` and `~/.dsh/zen-remote-server.json` — they migrate into the state file automatically on first start and are then deleted).
 
 </details>
 
@@ -90,9 +123,9 @@ cd ~/.dsh/profiles/desktop && pnpm install
 
 The same plugin supports two roles:
 - **Server (`role: host`, default)**: runs your sessions, spawns the local security gateway and Web Push service, and lets your phone (PWA) or another computer connect.
-- **Desktop Client (`role: client`)**: runs inside another computer's DSH desktop app, connects to the host, and mounts the host's shared sessions directly into its own sidebar (without spawning a local gateway or fighting for port 3088).
+- **Desktop Client (`role: client`)**: runs inside another computer's DSH desktop app, connects to **up to 8 hosts simultaneously**, and mounts their shared sessions directly into its own sidebar (without spawning a local gateway or fighting for port 3088).
 
-Open **Plugins → `dsh-zen-remote`** in DSH. The **Remote Access & Device Pairing** card sits right at the top of the page:
+Open **Plugins → `dsh-zen-remote`** in DSH. The **Remote Access & Device Pairing** card sits right at the top of the page (or run `npx dsh-zen-remote setup` on a headless server):
 
 ![Remote Access & Device Pairing overview card on the plugin detail page](docs/images/wizard-overview.png)
 
@@ -100,51 +133,47 @@ Open **Plugins → `dsh-zen-remote`** in DSH. The **Remote Access & Device Pairi
 
 ### Scenario A: Set up as Host (Phone & Desktop Access)
 
-Click **Start Setup Wizard** (or **Reconfigure Wizard** if already configured) to complete setup in three guided steps:
+Click **Start Setup Wizard** (or **Reconfigure Wizard**) to complete setup in three guided steps:
 
 #### Step 1: Choose "Act as Server (Host)" & an Access Method
 
 ![Wizard Step 1: Choose machine role and server access method](docs/images/wizard-step1-role-path.png)
 
-Pick one of the four access methods based on your network environment (switching methods automatically stops any managed process from the previous mode and updates the gateway bind address):
-
 | Access method | Best for | What the wizard automates |
 | --- | --- | --- |
-| **Managed Caddy (Recommended)** | Public IP (or router port forwarding) + domain on Cloudflare | Automatically downloads a prebuilt `Caddy + caddy-dns/cloudflare` binary (auto-accelerated via mainland China mirrors when needed) and issues/renews TLS certificates via DNS-01; gateway listens only on `127.0.0.1:3088` |
-| **Existing Reverse Proxy** | Already running Nginx, Caddy, or Lucky | Generates ready-to-paste proxy snippets with WebSocket and `X-Forwarded-*` headers, plus one-click `trustedProxies` registration (full manual guide: [docs/remote-access.en.md](docs/remote-access.en.md)) |
-| **Cloudflare Tunnel** | No public IP / no router port forwarding + domain on Cloudflare | Automatically downloads `cloudflared` (with mainland China mirror failover), creates or reuses a tunnel via the Cloudflare API, writes the DNS CNAME record, and starts the tunnel; gateway listens only on `127.0.0.1:3088` |
-| **LAN / Tailscale Direct** | Same Wi-Fi / LAN or shared Tailscale virtual network | No domain or TLS certificate needed; auto-detects the machine's LAN / Tailscale IPv4 address and binds `0.0.0.0:3088`, while the gateway's built-in **private-IP wall** rejects any unproxied direct connection from a public internet IP (`403 public-direct-forbidden`) |
+| **Managed Caddy (Recommended)** | Public IP (or router port forwarding) + domain on Cloudflare | Downloads prebuilt `Caddy + caddy-dns/cloudflare` and issues/renews TLS certificates via DNS-01 (`127.0.0.1:3088`) |
+| **Existing Reverse Proxy** | Already running Nginx, Caddy, or Lucky | Generates ready-to-paste proxy snippets + one-click `trustedProxies` registration ([manual guide](docs/remote-access.en.md)) |
+| **Cloudflare Tunnel** | No public IP / no port forwarding + domain on Cloudflare | Downloads `cloudflared`, creates/reuses a tunnel, configures CNAME, and starts the tunnel (`127.0.0.1:3088`) |
+| **LAN / Tailscale Direct** | Same Wi-Fi / LAN or shared Tailscale network | Auto-detects LAN / Tailscale IPv4 and binds `0.0.0.0:3088` behind the built-in **private-IP wall** (`403 public-direct-forbidden`) |
 
 #### Step 2: Fill in Connection Parameters
-- **Managed Caddy / Cloudflare Tunnel**: enter your public domain (e.g. `dsh.example.com`) and paste your Cloudflare API Token (click *"How do I get an API token?"* for step-by-step instructions and required permissions, or *"Domain not on Cloudflare yet?"* for onboarding steps).
-- **Existing Reverse Proxy**: enter the external `https://` URL of your proxy and copy the generated Nginx / Caddy / Lucky configuration snippet.
-- **LAN / Tailscale Direct**: the wizard automatically detects and pre-fills `http://<your-LAN-or-Tailscale-IP>:3088`.
+- **Managed Caddy / Cloudflare Tunnel**: enter your public domain (e.g. `dsh.example.com`) and paste your Cloudflare API Token.
+- **Existing Reverse Proxy**: enter the external `https://` URL and copy the generated Nginx / Caddy / Lucky configuration snippet.
+- **LAN / Tailscale Direct**: confirm the auto-detected `http://<your-LAN-or-Tailscale-IP>:3088` address.
 
 #### Step 3: Verify Connectivity & Pair Devices
 
 ![Wizard Step 3: Automatic connectivity check, phone QR pairing, and desktop client pairing](docs/images/wizard-step3-verify-pair.png)
 
-1. **Start Ingress Service & Auto-Probe**:
-   - For Managed Caddy or Cloudflare Tunnel, click **Start Caddy** or **Create & Start Tunnel** in the service bar.
-   - The wizard automatically probes **Local gateway ready** and **Access URL reachable** (verifying that `/` serves the `401` pairing page and `/lan-gate/admin` returns `403`).
-2. **Pair Phone / Browser (Web App)**:
-   - On the **Pair Phone / Browser (QR)** tab, click **Generate Pairing QR**.
-   - Scan the QR code with your phone camera or browser, enter the 8-character pairing code, and use **"Add to Home Screen"** to install DSH as a standalone PWA with lock-screen push notifications.
-3. **Pair Another Computer (Desktop Client)**:
-   - Switch to the **Pair Desktop Client** tab, click **Generate Desktop Pairing Code**, and click **Copy Server URL & Code** to send to your other computer.
+1. **Start Ingress Service & Auto-Probe**: click **Start Caddy** or **Create & Start Tunnel** if applicable; the wizard automatically checks **Local gateway ready** and **Access URL reachable**.
+2. **Pair Phone / Browser (Web App)**: on the **Pair Phone / Browser (QR)** tab, click **Generate Pairing QR**, scan with your phone, enter the 8-character code, and use **"Add to Home Screen"** to install DSH as a standalone PWA with lock-screen push.
+3. **Pair Another Computer (Desktop Client)**: switch to the **Pair Desktop Client** tab, click **Generate Desktop Pairing Code**, and click **Copy Server URL & Code**.
 
-> **Quick actions after setup**: once configured, you can directly click **Pair Phone (QR)**, **Pair Desktop Client**, or **Manage Devices** (rename devices, switch device roles, revoke one or all devices, or send a test push) right from the overview card footer without re-running the wizard.
+> **Quick actions after setup**: once configured, you can directly click **Pair Phone (QR)**, **Pair Desktop Client**, or **Manage Devices** right from the overview card footer without re-running the wizard.
 
 ---
 
-### Scenario B: Set up another computer as Desktop Client
+### Scenario B: Set up as Desktop Client (Connect up to 8 Hosts)
 
-On the second computer running the DSH desktop app:
+On another computer running the DSH desktop app (or via `dsh-zen-remote client pair <hostUrl> --code <8-char-code>` on the CLI):
 
-1. Open **Plugins → `dsh-zen-remote`** and click **Start Setup Wizard**.
-2. **Step 1**: select **Act as Desktop Client** and click **Next**.
-3. **Step 2**: enter a name for this computer (e.g. `Living-Room-Mac`), the host's gateway URL (`https://` for public URLs, or `http://192.168.x.x:3088` / `http://100.x.x.x:3088` for LAN / Tailscale), and the 8-character desktop pairing code from the host, then click **Pair & Connect**.
+1. Open **Plugins → `dsh-zen-remote`** and click **Start Setup Wizard** (or **+ Add Server** if already in client mode).
+2. **Step 1**: select **Desktop Client** and click **Next**.
+3. **Step 2**: enter this computer's display name (e.g. `Living-Room-Mac`), the host's gateway URL (`https://` for public URLs, or `http://192.168.x.x:3088` / `http://100.x.x.x:3088` for LAN / Tailscale), and the 8-character desktop pairing code from the host, then click **Pair & Connect**.
 4. **Step 3**: once all three status lights (**Pairing token**, **Server connection**, **Session & plugin sync**) turn green, the host's shared workspaces and sessions appear in your left sidebar immediately.
+5. **Multi-Server Management (up to 8 hosts)**:
+   - Click **+ Add Another Server** in Step 3, **+ Add Server** on the overview card, or **Manage Servers** to view per-server status, **Reconnect**, **Re-pair**, **Remove**, or **Remove All** (when all `8 / 8` slots are full, a red limit notice appears; re-pairing an existing URL still overwrites in place).
+   - Sidebar groups from all paired hosts merge **in pairing order** after your local workspaces. Duplicate host names are automatically numbered `Name-1`, `Name-2`; model pickers, connection status icons, read-only banners, plugin bridges, and file uploads are strictly isolated per host `serverId`.
 
 ---
 
@@ -153,18 +182,18 @@ On the second computer running the DSH desktop app:
 | | **Web App Device (Phone / Tablet / Browser)** | **Desktop Client (Another DSH Desktop App)** |
 | --- | --- | --- |
 | Visible sessions | **All** sessions on the host | **Only** sessions with remote access enabled on the host (enforced server-side) |
-| Credential | Long-lived HttpOnly cookie | Secret device token stored in the plugin config (`Bearer` token) |
+| Credential | Long-lived HttpOnly cookie | Secret device token stored in `~/.dsh/zen-remote-state.json` (`Bearer` token) |
 
 ### Enabling or Disabling Remote Access on a Session
 
-Remote access is controlled per session (or automatically enabled for new sessions if you turn on *Auto-share new sessions* in Step 2 of the wizard). You can toggle it from four places:
+Remote access is controlled per session (or automatically enabled for new sessions if you turn on *Auto-share new sessions*). You can toggle it from four places:
 
 1. **Host sidebar**: open a session's `"…"` menu and click **开启远程 / 关闭远程** (Enable / Disable remote);
 
    ![Enabling remote access from a session's menu on the host](docs/images/host-share-menu.png)
 
-2. **Host session header**: click the globe icon in the session title row (hover to see remaining idle time; a dot indicates a desktop client is currently viewing it);
-3. **Phone (Web App) session info card**: open the info card at the top right of a session and toggle **远程访问** (Remote access);
+2. **Host session header**: click the globe icon in the session title row (hover to see remaining idle time; a green dot indicates a desktop client is currently viewing it);
+3. **Phone (Web App) session info card**: open the `ⓘ` info card at the top right of a session and toggle **远程访问** (Remote access);
 
    <p align="center"><img src="docs/images/mobile-info-remote.png" alt="Remote access toggle inside the phone session info card" width="320"></p>
 
@@ -172,11 +201,11 @@ Remote access is controlled per session (or automatically enabled for new sessio
 
 ### Working in Remote Sessions on a Desktop Client
 
-- **Sidebar groups**: once a host workspace has at least one remote-enabled session, a **"Server Name · Workspace Name"** group appears in the client's sidebar. Click any session to view full history, stream responses, approve tools, use the server terminal, browse files and diffs, download deliverables, or drag-and-drop files to upload.
+- **Sidebar groups**: once a host workspace has at least one remote-enabled session, a **"Server Name · Workspace Name"** group appears in the client's sidebar (up to 8 paired hosts, stacked in pairing order). Click any session to view full history, stream responses, approve tools, use the server terminal, browse files and diffs, preview inline images, download deliverables, or drag/paste/pick files to upload.
 
   ![Remote workspace group in the desktop client sidebar](docs/images/client-sidebar.png)
 
-- **Closing & idle sleep**: a shared session automatically closes remote access after **48 hours** (`idleHours`) of inactivity (mid-turn sessions or sessions waiting on approvals/questions never sleep). When remote access is closed—or when the client unpairs or its token is revoked—remote sessions are automatically archived/hidden from the sidebar; an actively open session displays a "remote closed" banner and recovers automatically if re-shared.
+- **Closing & idle sleep**: a shared session automatically closes remote access after **48 hours** (`idleHours`) of inactivity (running or waiting sessions never sleep). Closed or unpaired sessions are automatically archived/hidden from the sidebar; an actively open session displays a "remote closed" banner and recovers automatically if re-shared.
 
   ![Banner shown when remote access is closed on an open session](docs/images/client-remote-closed.png)
 
@@ -184,34 +213,22 @@ Remote access is controlled per session (or automatically enabled for new sessio
 
 ## 4. Lock-Screen Push: When Notifications Fire
 
-Notifications fire only when **you are actually needed**, along two independent paths (all payloads are end-to-end encrypted with `aes128gcm`):
+Notifications fire only when **you are actually needed**, along two independent paths (all payloads are end-to-end encrypted with `aes128gcm`; toggle `pushEnabled` to disable all notifications and unregister `push_notify`, or enable `pushSessionName` to show `Session: <name>` on the first line of the notification body):
 
-1. **System-triggered (always on, never suppressed by debounce)**:
-   - **Tool waiting for approval**: pushes *"DSH needs your approval"* with the tool name. Waits `DSH_PUSH_APPROVAL_GRACE_MS` (default 5s) before sending so fast auto-approver plugins can answer first without buzzing your phone.
+1. **System-triggered (always on when `pushEnabled` is on, never suppressed by debounce)**:
+   - **Tool waiting for approval**: pushes *"DSH needs your approval"* with the tool name after `DSH_PUSH_APPROVAL_GRACE_MS` (default 5s, so fast auto-approvers can answer first without buzzing your phone).
    - **`ask_user_question` waiting for your answer**: pushes *"DSH is waiting for your answer"*.
-   - Works for both top-level sessions and subagent sessions across Web and Desktop hosts.
 2. **Model-triggered (`push_notify` tool)**:
-   - Called by the agent when you asked to be notified upon completion, or when it hits a blocker that requires your decision.
-   - Ordinary turn completions do not push by default (enable `pushTurnEnd` in advanced settings if you want a push after every turn; enable `pushSummary` to include up to 120 characters of the final reply in the notification body).
+   - Called by the agent when you asked to be notified upon completion, or when it hits a blocker that requires your decision. Ordinary turn completions do not push by default (enable `pushTurnEnd` if wanted; enable `pushSummary` to include up to 120 characters of the final reply).
 
 ---
 
 ## 5. Features
 
-- **Mobile PWA UI (Host)**:
-  - Two-level page stack (session list home + standalone session page with left-edge swipe back, Android back-gesture support, first-frame boot skeleton, and immutable asset caching)
-  - Home-screen plugin entry chips (auto-discovered per installed plugin, individually toggleable)
-  - Compact mobile composer with bottom sheets for permissions/models and direct phone attachment uploads
-  - Session info card (6-tile stats, log export, rename, fork, archive, one-tap full-conversation PNG share image, and remote access switch)
-- **Unified Setup & Pairing Wizard (2.3)**:
-  - Top-of-page 2×2 live overview card and 3-step modal wizard covering all four host ingress modes (Managed Caddy, Existing Reverse Proxy, Cloudflare Tunnel, LAN / Tailscale Direct) and Desktop Client pairing
-  - Automatic download of prebuilt `Caddy + caddy-dns/cloudflare` and `cloudflared` binaries with mainland China network auto-detection, mirror acceleration (`gh-proxy.com` / `ghfast.top`), connect/stall failover watchdogs, and daily upstream release tracking via GitHub Actions
-  - Automatic LAN / Tailscale IPv4 discovery and local network probing, backed by the gateway's private-IP wall (`403 public-direct-forbidden`) against accidental public exposure
-  - Dedicated **Manage Devices** modal and automatic sidebar cleanup on client unpair/revocation
-- **Cross-Desktop Remote Sessions (Client)**:
-  - Full-featured remote sessions in the sidebar: history, streaming, approvals/questions, server model catalog, file tree, changes summary/diff, server-side terminal, windowed artifact downloads, server-side LibreOffice PDF preview, up to 500 MiB file uploads, and drag-and-drop file upload interception; in remote sessions, non-image files added via the paperclip picker or pasted are likewise converted to byte uploads instead of unreadable local-path references
-- **Plugin Bridge**:
-  - Cooperative plugins and built-in adapters (such as `dsh-better-sidebar`) route their panel requests in remote sessions to the host machine (with explicit owner consent for whole-machine data). See [Plugin Bridge Guide](docs/plugin-bridge.md).
+- **Mobile PWA UI (Host)**: two-level page stack (session list home + session page with swipe-back and Android back-gesture support, first-frame boot skeleton, immutable asset caching), auto-discovered plugin entry chips, compact mobile composer with bottom sheets and phone attachment uploads, and a session info card (6-tile stats with `tok/s` output speed, log export, rename, fork, archive, one-tap full-conversation PNG share image, and remote access switch).
+- **Unified Setup Wizard & Headless CLI (`dsh-zen-remote`)**: top-of-page 2×2 live overview card, 3-step modal wizard, and a full-featured terminal CLI (`setup` / `status` / `host` / `client`) covering all four host ingress modes (Managed Caddy, Existing Reverse Proxy, Cloudflare Tunnel, LAN / Tailscale Direct with private-IP wall) and client pairing.
+- **Cross-Desktop Remote Sessions & Multi-Server Pool (Client)**: connect up to **8 main servers** simultaneously in pairing order; supports full history & live streaming, approval/question sync, per-server isolated model catalog, file tree & Git diffs, duplex server-side terminal (`terminal/attach`), inline Markdown image & media forwarding, windowed artifact downloads, server-side LibreOffice PDF preview, up to 500 MiB file uploads (drag-and-drop, paperclip picker, and paste), and one-click redacted diagnostics export.
+- **Plugin Bridge**: cooperative plugins and built-in adapters (such as `dsh-better-sidebar` `0.25.0`–`0.30.1`) route their panel HTTP and WebSocket requests in remote sessions to the host machine (with explicit owner consent for whole-machine data). See [Plugin Bridge Guide](docs/plugin-bridge.md).
 
 In depth: [Interface Design](docs/interface.md) · [Public Access & Relay Protocol](docs/remote-access.en.md)
 
@@ -219,21 +236,21 @@ In depth: [Interface Design](docs/interface.md) · [Public Access & Relay Protoc
 
 ## 6. Advanced Settings & Field Reference
 
-Day-to-day setup and device management are handled entirely by the **Remote Access & Device Pairing Wizard** at the top of the `dsh-zen-remote` page. To fine-tune individual low-level fields, click `dsh-zen-remote` a second time under **Included components** on the plugin detail page.
-
-<details>
-<summary>View underlying component settings screenshots & full field reference table</summary>
-
-Each field resolves in order: **environment variable > plugin row settings > `~/.dsh/lan-gate.config.json` > default**. Saving a field that requires a gateway/push restart reloads the plugin row automatically without restarting the app.
+Day-to-day setup and device management are handled entirely by the **Remote Access & Device Pairing Wizard** (or `npx dsh-zen-remote setup`). To fine-tune individual low-level fields, click `dsh-zen-remote` a second time under **Included components** on the plugin detail page.
 
 | Host Role & Pairing Cards | Shared Sessions List | Client Settings & Diagnostics |
 | --- | --- | --- |
 | ![Host role](docs/images/host-settings-role.png) ![Host pairing](docs/images/host-pairing.png) | ![Shared sessions](docs/images/host-settings-shares.png) | ![Client settings](docs/images/client-settings.png) |
 
+<details>
+<summary>Expand full configuration field reference table & environment variables</summary>
+
+Each field resolves in order: **environment variable > plugin row settings > `~/.dsh/lan-gate.config.json` > default**. Saving a field that requires a gateway/push restart reloads the plugin row automatically without restarting the app.
+
 | Field | Default | What it does |
 | --- | --- | --- |
 | `role` | `host` | `host` runs gateway + push + sharing; `client` connects to a remote host |
-| `serverName` | computer name | **Device name** (≤ 40 chars): sidebar group title on a host, registered device name on a client; syncs both ways automatically |
+| `serverName` | computer name | **Device name** (≤ 40 chars): sidebar group title on a host, registered device name on a client; renaming on a client broadcasts the new name to all its paired servers (one-way — the server never rewrites it) |
 | `port` | `3088` | Gateway port; retries upward (up to +20) if occupied |
 | `host` | `127.0.0.1` | Gateway bind address (`127.0.0.1` for local proxy/tunnel, `0.0.0.0` for LAN/Tailscale direct) |
 | `targetPort` | *(auto)* | Local DSH Web UI port; leave empty to auto-discover the host's listening port |
@@ -241,6 +258,8 @@ Each field resolves in order: **environment variable > plugin row settings > `~/
 | `trustedProxies` | empty | Comma-separated trusted proxy IPs when the reverse proxy runs on another machine |
 | `vapidSubject` | `mailto:admin@localhost` | Web Push contact (**must be a real `mailto:` or `https://` URL for iOS delivery**) |
 | `lang` | `auto` | Gateway & notification language: `auto` (browser `Accept-Language`), `zh`, or `en` |
+| `pushEnabled` | on | Master switch for session notifications; off stops every automatic push and unregisters the `push_notify` tool and its system-prompt hint |
+| `pushSessionName` | off | Open the notification body with `Session: <name>` (the source session's name; the title keeps the fixed event heading) |
 | `pushTurnEnd` | off | Also send a push when an ordinary turn finishes (approvals/questions always push) |
 | `pushEvents` | `agent/turn-stopping` | Comma-separated events that count as turn end when `pushTurnEnd` is on |
 | `pushDebounceMs` | `15000` | Minimum interval (ms) between automatic pushes |
@@ -249,13 +268,13 @@ Each field resolves in order: **environment variable > plugin row settings > `~/
 | `idleHours` | `48` | Idle-sleep window in hours for shared sessions; range `(0, 8760]` |
 | `autoShareNewSessions` | off | Automatically enable remote access on new sessions created on the host |
 | `pluginBridgeConsent` | `{}` | Whole-machine data consent map (`pluginName -> boolean`) for the plugin bridge |
-| `serverUrl` *(client)* | empty | Remote server gateway URL (`https://` required for public hosts; `http://` allowed on private LAN/Tailscale ranges) |
-| `deviceToken` *(client)* | empty | Paired client token (secret field, redacted everywhere) |
+| `serverUrl` *(client)* | empty | Remote server gateway URL (`https://` required for public hosts; `http://` allowed on private LAN/Tailscale ranges). Legacy single-server field: the paired list now lives in `~/.dsh/zen-remote-state.json` (up to 8 servers) and these row credentials migrate into it automatically on first start |
+| `deviceToken` *(client)* | empty | Paired client token (secret field, redacted everywhere). Legacy single-server field, migrated into `~/.dsh/zen-remote-state.json` like `serverUrl`; new pairings go through the settings card / wizard and never echo the token back to the browser |
 | `turnFoldDesktop` | off | Enable turn-process folding on desktop widths as well as mobile |
 | `keyboardLiftRatio` / `keyboardLiftMaxPx` / `keyboardSafetyPadPx` | `0.42` / `400` / `15` | Soft-keyboard lift calibration fallback for environments where the OS hides keyboard height |
 | `maxUploadBytes` | 20 MB | Mobile attachment upload cap |
 
-Legacy environment variables (outrank row settings): `LAN_GATE_PORT`, `LAN_GATE_HOST`, `LAN_GATE_TARGET_PORT`, `LAN_GATE_RATE_LIMIT`, `LAN_GATE_TRUSTED_PROXIES`, `LAN_GATE_VAPID_SUBJECT`, `LAN_GATE_LANG`, `DSH_PUSH_TURN_END`, `DSH_PUSH_EVENTS`, `DSH_PUSH_DEBOUNCE_MS`, `DSH_PUSH_SUMMARY`, `DSH_PUSH_TOOL`, `DSH_PUSH_LANG`, `DSH_PUSH_APPROVAL_GRACE_MS`.
+Legacy environment variables (outrank row settings): `LAN_GATE_PORT`, `LAN_GATE_HOST`, `LAN_GATE_TARGET_PORT`, `LAN_GATE_RATE_LIMIT`, `LAN_GATE_TRUSTED_PROXIES`, `LAN_GATE_VAPID_SUBJECT`, `LAN_GATE_LANG`, `DSH_PUSH_ENABLED`, `DSH_PUSH_SESSION_NAME`, `DSH_PUSH_TURN_END`, `DSH_PUSH_EVENTS`, `DSH_PUSH_DEBOUNCE_MS`, `DSH_PUSH_SUMMARY`, `DSH_PUSH_TOOL`, `DSH_PUSH_LANG`, `DSH_PUSH_APPROVAL_GRACE_MS`.
 
 </details>
 
@@ -263,23 +282,14 @@ Legacy environment variables (outrank row settings): `LAN_GATE_PORT`, `LAN_GATE_
 
 ## 7. Security Model, Version Tolerance & Known Notes
 
-### Security Model
-
-- **A paired desktop client is a trusted device**: the remote session terminal runs as the **host's OS user**, file-preview endpoints can read files accessible to the host process, and the client can create sessions in any host workspace.
-- **Unshared sessions are strictly isolated at the relay**: list rows, history, live events, approvals/questions, and embedded `dsh-session:` references for unshared sessions are filtered or refused server-side.
-- **Public direct-connection guard on `0.0.0.0`**: even when the gateway binds `0.0.0.0` for LAN / Tailscale mode, `isPrivateOrLoopbackIp` only admits direct connections from loopback, RFC1918 LAN ranges, link-local, and Tailscale (`100.64.0.0/10` / `fd7a:115c:a1e0::/48`); any unproxied direct connection from a public internet IP is rejected with `403 public-direct-forbidden`.
-- **Admin actions are local-only**: minting pairing codes, changing device roles, running the setup wizard, and revoking devices are only permitted directly on the host machine.
-- **Data & privacy**: the plugin reports nothing to any third party. Pairing state lives in `~/.dsh/lan-gate-state.json`, shared sessions in `~/.dsh/zen-remote-shares.json`, and Cloudflare tokens in `0600` files under `~/.dsh/zen-remote-ingress/`.
-
-### Version Tolerance
-
-1. **Relay protocol version**: both host and client must run the same `dsh-zen-remote` version.
-2. **DSH host version**: DSH versions may differ between host and client. Normalized interface fingerprints are compared during handshake; any differing group is annotated `"（版本有差异）"` and degrades only the affected panel.
-
-### Known Limitations & Third-Party Plugin Support
+- **Trusted client & strict session isolation**: a paired desktop client runs terminals and file previews as the host's OS user, while unshared sessions are strictly filtered and refused at the relay layer. Even when binding `0.0.0.0` for LAN/Tailscale, the gateway's private-IP wall rejects any unproxied public internet IP (`403 public-direct-forbidden`), and all admin/wizard mutations are restricted to the host machine itself.
+- **Version tolerance**: both ends must run the same `dsh-zen-remote` version; DSH host versions may differ (interface fingerprints are compared at handshake and degrade only mismatched panels).
 
 <details>
-<summary>Expand known limitations, iOS PWA notes & adapted third-party plugins</summary>
+<summary>Expand security & state-file details, known limitations, iOS PWA notes & adapted third-party plugins</summary>
+
+**Data & state files**
+- The plugin reports nothing to any third party. Pairing state lives in `~/.dsh/lan-gate-state.json`; the unified state file `~/.dsh/zen-remote-state.json` (`0600`) carries the local `serverId`, the shared-session table `sessions`, and the client's paired servers list `servers` (up to 8 servers, tokens included); Cloudflare tokens live in `0600` files under `~/.dsh/zen-remote-ingress/`.
 
 **Known limitations**
 - With multiple DSH windows open simultaneously on a client, active-session detection may occasionally dismiss a closed session early.
@@ -295,7 +305,7 @@ Legacy environment variables (outrank row settings): `LAN_GATE_PORT`, `LAN_GATE_
 
 | Plugin | Adaptation summary | Version tested |
 | --- | --- | --- |
-| [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar) | Full-screen mobile right-sidebar drawer with notch safe-area padding and swipe-back; **Plugin Bridge** built-in adapter for `0.25.0` through `0.30.0` (eight versions) (reads/writes host file/Git/task panels in remote sessions with host owner consent) | 0.19.1 / adapter 0.25–0.30.0 |
+| [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar) | Full-screen mobile right-sidebar drawer with notch safe-area padding and swipe-back; **Plugin Bridge** built-in adapter for `0.25.0` through `0.30.1` (nine versions) (reads/writes host file/Git/task panels in remote sessions with host owner consent) | 0.19.1 / adapter 0.25–0.30.1 |
 | [@nanmicoder/dsh-agent-teams](https://github.com/NanmiCoder/dsh-agent-teams) | Repositions AgentTeams floating pill below session header and preserves parent session back-link | 0.1.9 |
 | [@ychris12138/dsh-usage-stats](https://github.com/Ychris12138/dsh-usage-stats) | Moves usage & balance entry into the mobile home chips bar | 0.2.9 |
 | [@opendsh/dsh-plugin-scheduled-tasks](https://github.com/Ceelog/dsh-plugins) | Moves scheduled tasks entry into the mobile home chips bar | 0.2.3 |