dsh-zen-remote 1.1.16 → 2.0.0

package/docs/remote-access.md

@@ -1,6 +1,6 @@
 # 公网接入（通道半边详解）
 
-> `dsh-zen-remote` 的通道半边完整文档：反代对接、配对流程、环境变量、管理 API、推送、安全边界。
+> `dsh-zen-remote` 的通道半边完整文档：反代对接、设备角色与配对流程、环境变量、管理 API、远程中继、推送、安全边界。
 > 安装与快速上手见[根 README](../README.zh-CN.md)；界面侧细节见 [interface.md](interface.md)。
 > 网关基座衍生自 MIT 的 [`dsh-mobile-gate`](https://github.com/Bernardxu123/dsh-mobile-gate)。
 
@@ -10,16 +10,17 @@
 
 | 模块 | 说明 |
 | --- | --- |
-| 🔑 **公网身份** | 网关只监听 `127.0.0.1`，放在你自己的反代后面；新设备用配对码换取长期设备令牌（Cookie `lg_device`），身份跟着令牌走，与来源 IP 完全无关 |
+| 🔑 **公网身份** | 网关只监听 `127.0.0.1`，放在你自己的反代后面；新设备用配对码换取长期设备令牌（Web 应用端存 Cookie `lg_device`，桌面应用端拿 JSON 令牌），身份跟着令牌走，与来源 IP 完全无关 |
+| 👥 **设备角色** | 配对码生成时绑定角色：**Web 应用端**（手机/平板/浏览器，经网关访问全部会话）与**桌面应用端**（另一台 DSH 桌面端、zen-remote 子客户端角色，只能访问中继前缀、只见已共享会话）。拿错通道用码会被明确拒绝且不消耗码 |
+| 📡 **远程中继** | 桌面应用端与主服务端之间走 zen-remote 自己的中继协议（HTTP 单次调用 + NDJSON 流式订阅），服务端按「方法允许清单」逐请求复核会话归属，未共享会话的数据一步都出不来 |
 | 📱 **真 PWA** | `manifest.json` + service worker：反代带来 HTTPS 后，手机浏览器「添加到主屏」真正生效，全屏独立窗口运行，带图标/启动屏/主题色 |
-| 🧩 **可安装** | 主屏图标、`standalone` 显示、`apple-touch-icon`、maskable 图标 |
 | 🌐 **离线可用** | service worker（v3）：只有真正的静态壳（manifest/图标/离线页）缓存优先，其余（DSH 客户端 JS/CSS、API、页面 HTML）一律网络优先——装了新版本手机上立刻吃到，不会像早期版本那样在部署之后还残留旧 CSS |
 | 👆 **触屏手势** | 捏合缩放字体（可重置）；左缘返回手势已让位给界面半边（见下方「分工」），下拉刷新已整体移除（误触发全页重载会把人从对话中间弹回列表） |
 | 🔔 **卡住了就推送** | 真 Web Push（VAPID 签名 + aes128gcm 加密）。默认只在**真正需要你**的时候推：某个工具在等授权、模型在等你回答问题。「回合结束」默认不推（设 `DSH_PUSH_TURN_END=1` 打开）。通知里默认不带对话内容 |
-| 🛎️ **`push_notify` 工具** | 模型可主动调用的推送工具（在 `dsh-push.mjs` 里注册）：任务中途要用户拿主意、跑到关键节点、或出错需要人来处理时，模型自己决定推一条到锁屏。纪律写在工具描述里明确要求模型别高频用；宿主侧再兜底限流（同会话 60 秒最多 1 条、全局每小时最多 20 条），超额直接不发送、不报错。同样是 aes128gcm 端到端加密，推送服务器只见密文，暴露面只有你自己的锁屏。`lan-gate.config.json` 里 `pushTool: false`（或 `DSH_PUSH_TOOL=0`）可整体关掉；宿主没装工具注册服务（`ctx.tools`）时自动跳过，不影响插件其余功能 |
+| 🛎️ **`push_notify` 工具** | 模型可主动调用的推送工具（由推送半边注册）：任务中途要用户拿主意、跑到关键节点、或出错需要人来处理时，模型自己决定推一条到锁屏。纪律写在工具描述里明确要求模型别高频用；宿主侧再兜底限流（同会话 60 秒最多 1 条、全局每小时最多 20 条），超额直接不发送、不报错。同样是 aes128gcm 端到端加密，推送服务器只见密文，暴露面只有你自己的锁屏。`pushTool` 关掉（或 `DSH_PUSH_TOOL=0`）可整体关闭；宿主没装工具注册服务（`ctx.tools`）时自动跳过，不影响插件其余功能 |
 | 📐 **触屏布局** | 本仓库只留壳级规则（iOS 输入框防缩放、安全区滚动补偿、代码横向滚动）——排版类规则（44px 触摸目标、弹窗、composer 外观等）已交给界面半边，见下方「分工」——桌面零影响 |
 | 🔒 **桌面不受影响** | 所有规则都以 `html:not([data-lan-device="desktop"])`（或带同样排除条件的 `@media`）为根——只有显式标成「桌面」才会被排除，其余（包括真机默认的「自动」）都生效 |
-| 🛡️ **管理面本机独占** | 生成配对码、管理设备、触发推送——这些接口只认本机直连，经反代进来的请求一律 403 |
+| 🛡️ **管理面本机独占** | 生成配对码、管理设备、触发推送——这些接口只认本机直连，经反代进来的请求一律 403。2.0 起管理操作全部从 DSH「插件」页的设置区块发起（插件后台代为调用），`/lan-gate/admin` 页面只剩一段指向设置页的说明 |
 
 ---
 
@@ -31,17 +32,17 @@
                                        ▼
                      网关(独立 Node 子进程 · 默认只监听 127.0.0.1:3088)
                                        │
-        ┌──────────────────────────────┼────────────────────────────────┐
-        │                              │                                 │
-   未配对设备                    已配对设备(带 lg_device 令牌 Cookie)         本机直连(无 X-Forwarded-* 头)
-   → 任意路径都跳配对页             → 反代到 DSH Web UI(127.0.0.1:3080)         → 管理页/管理 API/推送触发
-     提交配对码换令牌                 HTML 注入：manifest + PWA 引导 +             /lan-gate/admin /status
-                                     触屏 CSS + randomUUID polyfill            /action /pair /pwa/push/send
+        ┌──────────────────┬───────────┴──────────────┬─────────────────────────┐
+        │                  │                          │                         │
+   未配对设备         Web 应用端(已配对)              桌面应用端(已配对)          本机直连(无 X-Forwarded-* 头)
+   → 任意路径都跳配对页  → 反代到 DSH(自动发现的          → 只放行中继前缀             → 管理页(只剩说明)/管理 API
+     提交配对码换令牌     实际端口)，带设备标记头            /_dsh/zen-remote/relay/*     /lan-gate/status /action /pair
+                       + Bearer 共享密钥，其余路径 403    (含共享密钥与设备标记头)       /pwa/push/send
 ```
 
-- 网关是独立子进程，与 DSH 主进程隔离：挂掉不影响主服务，插件停止时自动终止。
-- DSH 主服务本身仍然只监听 `127.0.0.1`，网关不改它的任何配置，也不碰它 `/api` 的信任栅栏。
-- 唯一保留的「按 IP 信任」：回环 socket 且不带任何 `X-Forwarded-*` 头的请求，判定为坐在这台机器前面的本机用户——这是管理面的唯一入口。经反代进来的请求一定带转发头，天然进不去。
+- 网关是独立子进程，与 DSH 主进程隔离：挂掉不影响主服务，插件停止时自动终止；主进程若死于非正常退出（崩溃、`kill -9`），子进程每 5 秒自检一次父进程存活，发现不在就自己退出，不占着端口。
+- DSH 主服务本身仍然只监听 `127.0.0.1`，网关不改它的任何配置，也不碰它 `/api` 的信任栅栏。转发目标端口自动发现（桌面端构建的 Web UI 端口可配置，网关读宿主的实际值）。
+- 唯一保留的「按 IP 信任」：回环 socket 且不带任何 `X-Forwarded-*` 头、且 **Host 去掉端口后是 `127.0.0.1` / `localhost` / `[::1]` 之一**的请求，判定为坐在这台机器前面的本机用户——这是管理面的唯一入口。经反代进来的请求一定带转发头，天然进不去。Host 检查挡的是 DNS 重绑定：攻击者自己的域名解析到 127.0.0.1 时，请求虽然从回环进来，Host 却不是回环名，进不了管理面。**注意这也是已知限制的根源**：同机联调时子客户端必须用局域网 IP 连网关，回环地址会被当成「本机直连」而不校验令牌。
 
 ---
 
@@ -72,11 +73,13 @@
 
 ### 1. 安装插件
 
+桌面端 App 与 Web 端都可以在左侧「插件」页 →「添加插件」→ 输入 `dsh-zen-remote` → 点「立即启用」；无头机器上的 Web 服务也可以用命令行：
+
 ```bash
-dsh plugin add dsh-zen-remote
+dsh plugin --profile web add dsh-zen-remote
 ```
 
-装完重启 `dsh web`。手动写法与本地开发装法见[根 README](../README.zh-CN.md#安装)；不走 `dsh plugin add` 的静态挂载见 [`cordis.patch.yml.example`](../cordis.patch.yml.example)。
+装完重启桌面端 App 或 `dsh web`。命令行不接受 `--profile desktop`（桌面端 profile 由 App 独占管理）；手动写法与本地开发装法见[根 README](../README.zh-CN.md#安装)；不走插件管理的静态挂载见 [`cordis.patch.yml.example`](../cordis.patch.yml.example)。
 
 ### 2. 配你自己的反代
 
@@ -231,14 +234,17 @@ sudo cloudflared service install      # 通了再装成常驻服务
 
 ### 3. 生成配对码、配对设备
 
-1. 反代配好后，在**这台机器本机**的浏览器打开 `http://127.0.0.1:3088/lan-gate/admin`。
-2. 点「生成配对码」，得到一个 8 位码，10 分钟内有效，只能用一次。
-3. 手机或另一台电脑，浏览器打开你反代的 HTTPS 域名，会看到配对页，输入配对码（可选填设备名）。
-4. 配对成功后自动进入 DSH Web UI（已注入 PWA），身份保存在长期 Cookie 里，换 Wi-Fi/换 IP 都不会掉线。
-5. 手机上通过浏览器菜单「添加到主屏幕」，就能像原生 App 一样独立打开。
-6. 页面会提示开启「任务完成推送」，同意通知权限后，agent 干完活即使切到别的 App 也能收到系统通知。
+2.0 起配对码从 DSH「插件」页 → dsh-zen-remote 设置区块生成（旧地址 `/lan-gate/admin` 只剩一段指向设置页的说明，仍只认本机直连）：
+
+1. 反代配好后，在**这台机器本机**打开 DSH「插件」页，展开 dsh-zen-remote 的设置区块。
+2. 选设备角色（Web 应用端 / 桌面应用端），点生成，得到一个 8 位码，10 分钟内有效，只能用一次。**码与角色绑定**：Web 应用端的码拿到桌面端去用会被拒绝，反之亦然；拿错的码不被消耗、也不计入错码锁定。
+3. Web 应用端：手机或另一台电脑的浏览器打开你反代的 HTTPS 域名，在配对页输入配对码（可选填设备名）。
+4. 桌面应用端：在另一台 DSH 桌面端的插件设置区块里把角色切成「子客户端」，填服务端地址与配对码。地址必须 https，只有内网/回环/Tailscale 段（`192.168.x`、`10.x`、`172.16–31.x`、`100.64.x`、`127.x`、`localhost`/`*.local`、IPv6 `::1`/`fc00::/7`/`fe80::/10`）才允许 http。
+5. 配对成功后自动进入 DSH Web UI（已注入 PWA），身份保存在长期 Cookie 里，换 Wi-Fi/换 IP 都不会掉线。
+6. 手机上通过浏览器菜单「添加到主屏幕」，就能像原生 App 一样独立打开。
+7. 页面会提示开启「任务完成推送」，同意通知权限后，agent 干完活即使切到别的 App 也能收到系统通知。
 
-在管理页还可以：把设备类型设为手机/电脑/自动排版、给设备改名、单独吊销某台设备或一键全部吊销。
+在设置区块还可以：改设备名、改设备角色（`set-role`）、单独/全部吊销设备。吊销立即生效——那台设备当前的连接与推送订阅一并销毁。桌面应用端够不到任何管理接口：网关只把它的请求转进中继前缀，其余路径（包括 DSH 页面和 `/api`）一律 403（`reason: 'relay-only'`）。
 
 ---
 
@@ -253,9 +259,10 @@ sudo cloudflared service install      # 通了再装成常驻服务
 | `LAN_GATE_TRUSTED_PROXIES` | 空 | 逗号分隔的 IP 列表。反代和网关不在同一台机器（回环地址）时，把反代的出口 IP 填进来，网关才会信任它带来的 `X-Forwarded-For`/`X-Forwarded-Proto` |
 | `LAN_GATE_VAPID_SUBJECT` | `mailto:admin@localhost` | Web Push 的 VAPID 联系人字段。**务必改成真实邮箱或 https 网址**：Apple 会用 `403 BadJwtToken` 拒绝占位符，导致 iOS 设备静默收不到推送（Google/Mozilla 不校验）。填错时启动日志有告警 |
 | `LAN_GATE_LANG` | `auto` | 网关自己那几个页面（配对页、限流页、管理页）和注入到应用里的推送开关卡片用什么语言。`auto` 按请求的 `Accept-Language` 决定——配对访客唯一会主动交出的语言信号；没有这个头就用中文。`zh`/`en` 写死，不再看浏览器 |
-| `DSH_PUSH_LANG` | `zh` | 推送通知本身的文案语言（等授权 / 等回答 / 回合完成）。这里**不做自动探测**：通知是宿主进程生成的，既没有请求头，`launchd` 也不给它 `LANG`（中文用户的机器上 `Intl` 照样报 `en-US`）。要英文就显式设 `en` |
+| `LAN_GATE_RELAY_SECRET` | （自动生成） | 中继共享密钥，2.0 起桌面应用端的请求靠它向 DSH 的中继路由自证「标记头是网关写的」。**由插件在每次加载主入口时现生成**（32 字节随机数经环境变量交给网关子进程，无条件覆盖），**不可由外部指定**——宿主环境里手工设置的值会在子进程启动时被覆盖或删除；插件没带（client 角色、旧式独立加载）时密钥功能关闭，网关对空密钥不加头 |
+| `DSH_PUSH_LANG` | `zh` | 推送通知本身的文案语言（等授权 / 等回答 / 回合完成）。2.0 起它只是对设置里 `lang` 的环境变量覆盖；都不设时中文。这里**不做自动探测**：通知是宿主进程生成的，既没有请求头，`launchd` 也不给它 `LANG`（中文用户的机器上 `Intl` 照样报 `en-US`）。要英文就显式设 `en` |
 
-除了环境变量，**推荐用配置文件** `~/.dsh/lan-gate.config.json`（网关和推送插件两半共用一份，改完重启 `dsh web` 生效；显式环境变量优先于文件）：
+除了环境变量，**推荐在 DSH「插件」页的设置区块里改配置**（全部字段的字段表见根 README）；`~/.dsh/lan-gate.config.json` 作为旧配置仍然生效。每个字段的优先级是 **环境变量 > 插件行设置 > `lan-gate.config.json` > 默认值**，某层的值不合法时该层视为未设置（手写坏 `port: "abc"` 会露出文件层的端口，而不是报错）。文件键名 = 环境变量去掉前缀转小驼峰：
 
 ```json
 {
@@ -266,26 +273,72 @@ sudo cloudflared service install      # 通了再装成常驻服务
 }
 ```
 
-字段名 = 环境变量去掉前缀转小驼峰：`port` / `host` / `targetPort` / `rateLimit` / `trustedProxies` / `vapidSubject`，推送半边是 `pushTurnEnd`（回合结束是否推送，默认 `false`）/ `pushEvents` / `pushDebounceMs` / `pushSummary` / `pushTool`（`push_notify` 工具开关，默认 `true`）。语言只有一个键 `lang`，两边共用：网关认 `auto`（跟随浏览器）/`zh`/`en`，推送半边只认 `en`，其余一律中文——所以 `"lang": "auto"` 的意思是「页面跟随浏览器、通知保持中文」。挂载行支持 Cordis config 的 DSH 版本也可以把网关配置写在 insert 行的 `config:` 下（同名小驼峰字段），效果等同。
+推送半边另有 `pushTurnEnd` / `pushEvents` / `pushDebounceMs` / `pushSummary` / `pushTool`，语言只有一个键 `lang`，两边共用：网关认 `auto`（跟随浏览器）/`zh`/`en`，推送半边只认 `en`，其余一律中文——所以 `"lang": "auto"` 的意思是「页面跟随浏览器、通知保持中文」。还有两个键不在设置面板里：`pushApprovalGraceMs`（等授权推送的等待窗口，也可用环境变量 `DSH_PUSH_APPROVAL_GRACE_MS`）。`role`、`serverName`、`idleHours`、`autoShareNewSessions`、`serverUrl`、`deviceToken` 是 2.0 新字段，走设置页或插件行，不在旧文件里读——`role` 例外，文件层也认（`host`/`client`）。
+
+改完需要重启网关/推送的字段（`role`、`port`、`host`、`targetPort`、`rateLimit`、`trustedProxies`、`vapidSubject`、`lang` 与推送各字段），插件自己检测指纹变化并重载插件行，网关子进程随之重启——不用手动重启 App。
 
-推送半边（`dsh-push.mjs`）随包自带，装包即挂载，**不需要在 profile 的
-`cordis.patch.yml` 里手写任何一行**。从旧的两包结构升级上来的话，profile patch
-里那行手挂的 `网关半边/dsh-push.mjs` 要删掉，否则会重复挂载。
+2.0 起网关与推送**不再各占一行**：包自带的 `cordis.patch.yml` 只挂 `dsh-zen-remote` 一行，主入口按 `role` 用 `ctx.plugin()` 加载这两个子插件，并把合并后的生效配置传给它们。profile 补丁里残留的旧 `dsh-zen-remote-gateway` / `dsh-zen-remote-push` 行会被 loader 警告并跳过，删掉即可——照老例子再手挂一行网关会拉起第二个网关进程抢端口。
 
 ---
 
 ## 🔌 管理 API
 
-以下接口全部**仅限本机直连**：请求的 socket 必须是回环地址、且不带任何 `X-Forwarded-*` 头。只要请求经过反代（一定带转发头），一律返回 403——公网碰不到这些接口。
+以下接口全部**仅限本机直连**：请求的 socket 必须是回环地址、且不带任何 `X-Forwarded-*` 头、且 Host 是回环名（见上）。在这道判定之外还有两道针对浏览器的门（网页发出的跨站 POST 不需要预检，光靠 socket/Host 判定挡不住）：请求带 `Origin` 头一律 403，带请求体但 `Content-Type` 不是 `application/json` 一律 415——插件后台的代调用和脚本 `curl`（带 JSON 头、无 Origin）都不受影响。只要请求经过反代（一定带转发头），一律返回 403——公网碰不到这些接口。2.0 起这些接口的调用方从浏览器管理页换成了插件后台：设置页发起的请求走 DSH 同源路由 `/_dsh/zen-remote/admin/*`，由主服务端进程以「本机直连」的身份代调下面这些网关接口（带 `x-zen-remote-via` 标记的转发请求只许查看、拒绝变更——唯一例外是 `/_dsh/zen-remote/admin/shares` 的开关会话远程：Web 应用端（手机）可以开关，手机会话信息卡片里的「远程访问」开关就走这条）。
 
 | 接口 | 方法 | 作用 | 参数 |
 | --- | --- | --- | --- |
-| `/lan-gate/pair` | POST | 生成一个新的一次性配对码（10 分钟有效） | 无 |
-| `/lan-gate/status` | GET | 查看运行状态、当前配对码、已配对设备列表 | 无 |
-| `/lan-gate/action` | POST | 管理设备 | `action`: `set-kind` / `rename` / `revoke` / `revoke-all`；`id`: 设备 id（`revoke-all` 不需要）；`set-kind` 还需要 `kind`（`phone`/`desktop`/`auto`）；`rename` 还需要 `name` |
+| `/lan-gate/pair` | POST | 生成一个新的一次性配对码（10 分钟有效）。**码与角色绑定** | `role`（可选）：`desktop-client` 生成桌面应用端码；缺省/无法解析时为 Web 应用端码。响应带 `role` |
+| `/lan-gate/status` | GET | 查看运行状态、当前配对码、已配对设备列表（每台带 `role`） | 无 |
+| `/lan-gate/action` | POST | 管理设备 | `action`: `set-role` / `set-kind` / `rename` / `revoke` / `revoke-all`；`id`: 设备 id（`revoke-all` 不需要）；`set-role` 还需要 `role`（`web`/`desktop-client`，改成 `desktop-client` 时推送订阅一并删除）；`set-kind` 还需要 `kind`（`phone`/`desktop`/`auto`）；`rename` 还需要 `name` |
 | `/pwa/push/send` | POST | 给所有已订阅设备发一条推送 | `title`、`body`（都是纯文字，不含对话内容） |
 
-配对入口 `/lan-gate/pair/claim`（POST）是唯一对外开放的例外——它就是设备输入配对码换令牌的地方，靠码本身（一次性、10 分钟过期）和失败锁定（连续 5 次错码锁该 IP 15 分钟）来防护，不需要本机身份。
+配对兑换入口是仅有的对外开放例外，靠码本身（一次性、10 分钟过期）和失败锁定（连续 5 次错码锁该 IP 15 分钟）防护，不需要本机身份，两个通道各认各的角色：
+
+- `/lan-gate/pair/claim`（POST）——浏览器配对页用，只收 **Web 应用端**码，成功发 Cookie；
+- `/lan-gate/pair/claim-desktop`（POST）——子客户端配对用，只收**桌面应用端**码，令牌放在 JSON 响应体里（`{ok, id, name, token}`），从不种 Cookie。
+
+角色不匹配的兑换返回 403 `role-mismatch` 和一段本地化的提示文案；错通道的码不消耗、也不计锁定。
+
+---
+
+## 📡 远程中继（桌面应用端的数据通道）
+
+桌面应用端没有 DSH 的登录 Cookie，也不直接转发 DSH 的原生 `/api` 和 WebSocket——它和主服务端之间走 zen-remote 自己的中继协议：**单次调用是普通 HTTP POST，每条流式订阅是一个 HTTP 流式响应**，全部挂在主服务端插件的专用前缀 `/_dsh/zen-remote/relay/` 下，经网关进出。插件不自己实现 WebSocket；客户端中止请求即取消订阅。
+
+**三道门，逐请求复核**：
+
+1. **网关设备认证**：请求必须带有效的桌面应用端设备令牌（Bearer），网关只放行它去中继前缀；
+2. **标记头 + 共享密钥**：网关给每个放行的转发请求盖上 `x-zen-remote-via: gateway`、`x-zen-remote-role`、`x-zen-remote-device` 和 `x-zen-remote-secret`（共享密钥）四个头（客户端伪造的同名头在入口就被剥掉）；中继路由逐次校验密钥与三个标记头，任何一项不对一律 401。没有这道密钥，本机其他进程可以直连 `127.0.0.1` 伪造标记头冒充网关；
+3. **按方法登记的访问控制**：每个允许的方法登记它的会话归属字段，授权只看登记的字段，表里没有的方法一律拒绝——**不是**「从参数里通用扫描会话 id」（那种写法会被诱饵字段骗过：塞一个已共享会话的 id 进不认识的名字里，DSH 的参数校验会悄悄丢掉它）。
+
+**路由一览**（前缀 `/_dsh/zen-remote/relay`）：
+
+| 路由 | 方法 | 作用 |
+| --- | --- | --- |
+| `/ping` | GET | 存活探测，`{ok:true}` |
+| `/v1/handshake` | POST | 握手：交换中继协议版本、服务端 id / 显示名、DSH 版本号、接口指纹表。中继协议版本不一致即拒绝连接；回包带 `serverName`（服务端显示名）与 `deviceName`（本设备在服务端记录里的名字） |
+| `/v1/device/name` | POST | 设备改名：**网关自己处理、不转发给 DSH**——只对已配对的桌面应用端开放，只改调用者自己的设备记录；请求体 `{"name":"…"}`（1–40 字），改名经流心跳（约 15 秒）与握手刷新（约 30 秒）同步到对端 |
+| `/v1/invoke` | POST | 在已共享会话上执行一次 DSH 远程调用（单次，JSON 进出） |
+| `/v1/stream` | POST | 打开一条 DSH 流式订阅。**NDJSON 格式**：响应体每行一条 JSON；`{"type":"ping"}` 心跳行（默认 15 秒一条）防止反代把闲置流掐掉，每条都带当下的 `serverName` / `deviceName`（服务端改名约 15 秒内到达所有客户端）；共享关闭/订阅失效时补一行 `{"type":"error","error":{"code":"unshared"}}` 再结束 |
+| `/v1/event-result` | POST | 审批/提问这类「需要应答事件」的应答回传（`{eventId, result}`），服务端按转发记录核对归属后转交 |
+| `/v1/http` | POST | 改动摘要 / diff 面板的 plain-HTTP 长尾：请求体 `{route, query}` 只登记 `changes.summary` / `changes.diff` 两条、只转发 GET（查询串是这次调用的坐标，不是要转发的请求体）；查询串按允许清单**规范化重建**——只保留 `sessionId`（恰好一次，过共享表）与 `seq` / `index`（至多一次、十进制非负整数），未知参数丢弃，合成 URL 只由规范化结果拼成（两次解析对控制字符的处理差异曾是越权读取口子）——随后**进程内**交给宿主 `/api` 共享 fetch handler，不走回环 HTTP |
+| `/v1/upload` | POST | 远程会话的**非图片附件**上传：请求体是原始字节流（不是 JSON）；查询串按允许清单规范化重建——只保留 `sessionId`（恰好一次、过共享表，未共享 403）与 `name`（至多一次）；上限 100 MiB，`Content-Length` 预检加流式计数双保险，超限 413（先回拒绝再排空尾部字节）；每设备并发 8（超出 429）；随后与 `/v1/http` 一样**进程内**交给宿主 `/api` 共享 handler——上传回执落进的会话与之后 `session/prompt` 解析附件引用的会话是同一个 |
+| `/v1/unshare` | POST | 子客户端主动关闭某会话的远程（只认共享表内的会话） |
+
+**允许清单里的方法**（其余一律 `forbidden-method`）：会话读写（`session/follow`、`session/page`、`session/prompt`、`session/cancel`、`session/rename`、`session/selectModel`、`session/updateQueue`、`session/attachment`、`session/projections`）、新建与分叉（`session/create`、`session/fork`，结果自动共享）、子智能体（`subagents/prompt`、`subagents/interruptByParent`，按父会话判定）、附件与 @ 引用（`fileUploads/upload`、`fileReferences/list`、`sessionReferenceResolver/candidates`）、面板长尾（`goals/*` 五个、`commands/list|execute`、`agentPresets/select`、`sessionFeedback/record`）、文件树与预览（`workspaceFiles/list|changes|read|readBytes|stat`）、终端（`terminal/*`）、任务（`job/list|follow|kill`）、`skills/list`、消息反馈（`messageFeedback/*`）、`schedule/list`、工作区会话操作（`workspace/pinSession` 等）、以及四个全局读：`session/control` 流、`session/list`、`workspace/follow` 流与 `session/modelCatalog`。前三个不带会话参数，安全靠**输出过滤**：每一帧/每一行结果先按共享表过滤，未共享会话的行到不了客户端；`session/list` 结果行里指向不可访问会话的 `parentSessionId` 字段也会被删掉（行的其余部分照常透传）。`session/modelCatalog` 同样无参数、全局只读——它就是服务端的模型提供方目录，只有分组与模型 id、显示名，不带会话数据；服务端会把结果里的 `failures` 数组清空（宿主的逐组错误文本可能带端点或凭据细节，客户端本来也不展示它）。`sessionReferenceResolver/candidates`（@ 引用候选）的答案带**每一个**服务端会话的标题、目录与现成 mention，同样走行级输出过滤，只放行已共享会话的行。审批/提问事件经 `$zr/events` 订阅转发，逐事件按 `agentId` 判定可达性。
+
+`/v1/http` 那条路由是另一张按**路由名**登记的允许清单（不是方法表的一部分），纪律相同：表外路由一律 404，登记的路由只按声明的会话参数判定；子客户端一侧的对应入口是 `GET /_dsh/zen-remote/client/http/<route>`——浏览器 fetch 包装拦下的 `/api/changes.*` 虚拟 id 请求改道到这里，还原原始 id 后经中继转发，上游 Content-Type 只认 JSON，其余一律降级为 `text/plain` + `nosniff`。
+
+`/v1/upload` 这条路由的起点在**子客户端本机**：DSH 的非图片附件上传走 Web Worker 里发出的请求，`window.fetch` 包装与 typert 拦截都够不到它，所以插件在子客户端本机后台包装宿主连接服务 `fetchRoutes` 表里的上传路由（`/api/session/uploadFileBinary`）把请求接住——带虚拟会话 id 的上传经中继流式转到服务端（本机 id 的上传原样放行、请求体一个字节不碰），超上限在子客户端本地直接拒，慢链路受客户端侧 300 秒超时约束且上传的超时与传输失败不改连接状态。本地失败也按宿主自己的「200 + 失败信封」格式回给界面，中文错误文案直接落在附件卡片上。导出（`/api/session.export`）是同一次包装的另一项：虚拟 id 的导出请求后台直接 403 `remote-unsupported`（界面里菜单项也已隐藏）。
+
+**安全边界**：
+
+- 中继执行时用的是 DSH 网关服务的公开调用方法，身份是操作者身份，**不在服务端替换任何 DSH 内部方法**；
+- 子智能体/分叉会话不单独落表，可达性按「祖先链上有已共享会话」判定；
+- `dsh-session:` 会话引用也会被扫描：DSH 会在**发消息**（`session/prompt` / `subagents/prompt` 的 content 文本块）、**改写排队消息**（`session/updateQueue` 的 edit 内容）与**斜杠命令**（`commands/execute` 参数里的全部字符串——命令处理器会把原始输入拼进下一条用户消息）这三条路径上注入被引用会话的内容，且注入时不再做权限检查，所以引用指向未共享会话的调用在服务端直接 403；@ 引用候选（`sessionReferenceResolver/candidates`）的答案也只放行已共享会话的行；
+- 终端是有意开放的（桌面应用端是可信设备）：开的是**服务端**的 PTY，以服务端用户身份运行、不受智能体沙箱与审批限制；关闭会话的远程时终端流一并终止；
+- `workspaceFiles/read` 等文件预览接口不限制在会话目录内（DSH 自身就不限制），服务端进程可读的文件都能读——信任前提与终端相同；
+- 每台设备并发流数有上限（32）、同时在途的 invoke 数也有上限（32，超出 429 `too-many-invokes`）；`*/internal` 形状的错误码（`gateway/internal` 等）只回码不带消息——那类消息引用的是服务端内部细节。事件应答按「转发时的订阅 + 设备」核对归属。审批/提问的转发是**先到先得**：服务端自己的界面和子客户端谁先应答谁生效，后答的一方被网关拒绝、同步成「已处理」。中继**不代答**：未共享会话的审批/提问事件不会被转发，服务端界面也不在线时这个审批就一直等待——网关会把仍未应答的事件转交给下一个连上来的订阅，等，而不是替你拒绝（代答会把整批待审批一次性判死，砸掉「推送 → 唤醒 → 审批」链路）。未共享会话的**通知类**事件（EMIT 帧：会话列表摘要、账号到期之类的服务端全局状态）一律不转发。
 
 ---
 
@@ -305,14 +358,18 @@ sudo cloudflared service install      # 通了再装成常驻服务
 
 **防住了什么：**
 - 配对码暴力破解——码本身 10 分钟一次性，连续 5 次错码会把那个来源 IP 锁 15 分钟。
-- 令牌可以随时吊销——手机丢了、借给别人用完了，管理页点一下就失效，立即生效。
-- 请求量——按解析出的真实客户端 IP 限流，默认每分钟 120 次，超了就 429。
-- 管理面只有本机能碰——生成配对码、管理设备、触发推送，这些接口只认本机直连，经反代来的请求（一定带转发头）一律 403。
+- 码与角色绑定——Web 应用端的码进不了桌面通道，反之亦然；拿错的码不消耗、不计锁定。
+- 令牌可以随时吊销——设备丢了、借给别人用完了，设置页点一下就失效，立即生效（连接、HTTP 长流与推送订阅一并销毁）。
+- 桌面应用端被关进中继前缀——它访问其余任何路径（包括 DSH 页面和 `/api`）一律 403。
+- 中继三道门——设备令牌、网关标记头 + 每次加载现生成的共享密钥（`LAN_GATE_RELAY_SECRET`，不可外部指定）、按方法登记的允许清单 + 输出过滤；未共享会话的数据一步都出不来。
+- 请求量——**未配对**的请求按解析出的真实客户端 IP 限流，默认每分钟 120 次，超了就 429；已配对设备不受这条限制（桌面应用端另有中继自己的并发上限）。
+- 管理面只有本机能碰——生成配对码、管理设备、触发推送，这些接口只认本机直连（回环 socket、无转发头、回环 Host），经反代来的请求（一定带转发头）一律 403；带 `Origin` 的请求与带非 JSON 请求体的请求也一样 403/415，DNS 重绑定与跨站简单请求进不来；带网关标记头的请求即使本机直连也拒绝变更动作（开关会话远程除外，见上）。
 
 **没防住什么，需要你自己注意：**
 - 反代配置错了——比如不小心把 `127.0.0.1:3088/lan-gate/admin` 也挂到公网域名下，或者 `X-Forwarded-Proto` 设错导致网关判断错客户端协议，这些是配置问题，网关本身防不住。
-- 令牌被别人拿到——这是单用户工具，令牌等于访问权限，没有更细的权限分级；谁拿到令牌谁就能用，怀疑泄露就去管理页吊销重配。
-- DSH 自身的能力边界——网关只负责把 HTTPS 流量安全地转发给 DSH，不会也不能给 DSH 本身加它没有的安全措施（比如 `/api` 自己的信任栅栏是 DSH 那边的事）。
+- 令牌被别人拿到——这是单用户工具，令牌等于访问权限，没有更细的权限分级；谁拿到令牌谁就能用，怀疑泄露就去设置页吊销重配。
+- **桌面应用端是可信设备**——它的终端以服务端用户身份运行、不受智能体沙箱与审批限制，文件预览不限制在会话目录内，还能在服务端任意工作区新建会话。「只有已共享会话可见」约束的是会话数据，不是这台机器；把配对码给不值得信任的计算机等于把机器交给它。
+- DSH 自身的能力边界——网关只负责把流量安全地转发给 DSH，不会也不能给 DSH 本身加它没有的安全措施（比如 `/api` 自己的信任栅栏是 DSH 那边的事）。
 - 状态文件 `~/.dsh/lan-gate-state.json` 明文存着 VAPID 私钥和所有设备的令牌——这个文件本身就等于全部访问权限，注意宿主机上它的文件权限，别把 `~/.dsh` 目录同步进公共网盘或备份到不受信的地方。
 
 ---
@@ -335,7 +392,7 @@ sudo cloudflared service install      # 通了再装成常驻服务
 旧版是按来源 IP 审批的，这套逻辑在新的令牌模型下没有意义。网关用新版本第一次启动时，会检测到旧的状态文件并直接把它改名归档成 `lan-gate-state.json.v1.bak`（不做数据迁移）。所有设备都需要重新走一遍配对流程。
 
 **配对码提示过期或不对怎么办？**
-配对码 10 分钟有效、用一次就失效，过期或用过了要回到本机管理页重新点「生成配对码」。如果连续输错 5 次，那个来源 IP 会被锁 15 分钟，等一等或者换个网络再试。
+配对码 10 分钟有效、用一次就失效，过期或用过了要回到服务端的插件设置页（DSH「插件」页的 dsh-zen-remote 区块）重新生成。如果连续输错 5 次，那个来源 IP 会被锁 15 分钟，等一等或者换个网络再试。
 
 **推送收不到怎么排查？**
 按顺序查：手机是不是用 HTTPS 域名访问的（HTTP 下浏览器根本不会注册 Service Worker，推送无从谈起）？浏览器/PWA 有没有被系统或用户拒绝通知权限？可以到本机管理页对应的状态接口（`/lan-gate/status`）看这台设备名字后面有没有 🔔 标记，确认订阅到底成功没有。
@@ -354,8 +411,8 @@ npm test   # 起 mock 上游，跑 gateway/auth/push 三组测试：反代与注
 
 | 路径 | 作用 |
 | --- | --- |
-| `lan-gate.mjs` | Cordis 插件入口：spawn 网关子进程 + 生命周期管理 |
-| `dsh-push.mjs` | （可选）agent 完成推送宿主插件，调网关本机 `/pwa/push/send`；同时注册模型工具 `push_notify` |
+| `lan-gate.mjs` | 网关子插件入口，由主入口按 host 角色加载：spawn 网关子进程 + 生命周期管理 |
+| `dsh-push.mjs` | 推送子插件（与网关一起由主入口加载）：监听 DSH 事件总线调网关本机 `/pwa/push/send`，并注册模型工具 `push_notify` |
 | `lib/lan-gate-server.cjs` | 网关本体：单文件 CommonJS（Node stdlib + `web-push` 一个运行时依赖），HTTP/WebSocket 反代 + 配对/令牌 + 限流 + PWA 注入 + Web Push |
 | `pwa/manifest.json` | PWA 安装清单 |
 | `pwa/sw.js` | service worker（离线缓存 + 推送通知） |

package/dsh-push.mjs

@@ -32,34 +32,21 @@ export const name = 'dsh-zen-remote-push'
 export const inject = []
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
-
-// Shares the gateway's optional config file <DSH_HOME>/lan-gate.config.json
-// (keys: port, lang, pushEvents, pushDebounceMs, pushSummary, pushTurnEnd, pushTool).
-// Explicit env wins.
-import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { homedir } from 'node:os'
-function fileConfig() {
-  try {
-    const raw = JSON.parse(readFileSync(join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'lan-gate.config.json'), 'utf8'))
-    return raw !== null && typeof raw === 'object' ? raw : {}
-  } catch { return {} }
-}
-const truthy = (v) => v === true || v === 1 || v === '1'
-const FILE = fileConfig()
-const GATEWAY_PORT = Number(process.env.LAN_GATE_PORT ?? FILE.port ?? 3088)
-const EVENTS = String(process.env.DSH_PUSH_EVENTS ?? FILE.pushEvents ?? 'agent/turn-stopping').split(',').map((s) => s.trim()).filter(Boolean)
-const DEBOUNCE_MS = Number(process.env.DSH_PUSH_DEBOUNCE_MS ?? FILE.pushDebounceMs ?? 15000)
-const INCLUDE_SUMMARY = process.env.DSH_PUSH_SUMMARY !== undefined ? process.env.DSH_PUSH_SUMMARY === '1' : truthy(FILE.pushSummary)
-const TURN_END_ENABLED = process.env.DSH_PUSH_TURN_END !== undefined ? process.env.DSH_PUSH_TURN_END === '1' : truthy(FILE.pushTurnEnd)
-const PUSH_TOOL_ENABLED = process.env.DSH_PUSH_TOOL !== undefined ? process.env.DSH_PUSH_TOOL !== '0' : FILE.pushTool !== false
+// Config arrives as apply(ctx, config)'s already-resolved values — every
+// field merged from env > plugin row > lan-gate.config.json > defaults
+// (src/config.ts). Standalone loads (old single-row setups, tests) resolve
+// the same way on the spot. No module-top-level config constants: everything
+// below is computed per apply() call and passed down as arguments.
+import { readFileConfig, resolveConfig } from './lib/config.js'
 
 // Notification language. The gateway resolves the same `lang` key to the
 // requesting browser's Accept-Language when it is "auto"; a notification has
 // no such reader signal, and the host process has no usable locale either
 // (launchd starts it with no LANG — Intl reports en-US on a Chinese machine),
-// so anything other than "en" here means Chinese.
-const LANG = String(process.env.DSH_PUSH_LANG ?? FILE.lang ?? 'zh') === 'en' ? 'en' : 'zh'
+// so anything other than "en" here means Chinese. DSH_PUSH_LANG keeps
+// precedence over the resolved `lang` field. Resolved at call time (not at
+// import) so policy tests can flip the variable per call.
+const resolveLang = (lang) => String(process.env.DSH_PUSH_LANG ?? lang ?? 'zh') === 'en' ? 'en' : 'zh'
 const COPY = {
   zh: {
     lastTool: '最后执行了 {tool}',
@@ -82,7 +69,6 @@ const COPY = {
     turnEndBody: 'The agent finished the current turn'
   }
 }
-const T = COPY[LANG]
 
 // The model-facing tool of @deepseek-ai/dsh-tool-ask-user. Its `tool/call`
 // session event is appended BEFORE dispatch (dsh-agent-loop appendToolCall),
@@ -105,16 +91,19 @@ const ASK_USER_TOOL = 'ask_user_question'
 // 5000ms covers a machine answerer with margin while still reaching a phone
 // promptly when a human really is needed. Raise it if your answerer is slower
 // than that; the cost of a longer window is only that genuine prompts notify
-// later.
-const APPROVAL_PENDING_MS = Number(
-  process.env.DSH_PUSH_APPROVAL_GRACE_MS ?? FILE.pushApprovalGraceMs ?? 5000
-)
+// later. Not part of the T12 config table: DSH_PUSH_APPROVAL_GRACE_MS and the
+// legacy `pushApprovalGraceMs` file key keep working as before, read per
+// apply() so tests can shrink the window.
+function approvalPendingMs(fileConfig) {
+  return Number(process.env.DSH_PUSH_APPROVAL_GRACE_MS ?? fileConfig.pushApprovalGraceMs ?? 5000)
+}
 
 // Low-level sender shared by every leg: POSTs to the gateway's local
 // /pwa/push/send, which does the actual VAPID + aes128gcm encrypted delivery
 // to every subscribed device and replies { ok, sent, failed }.
-async function sendPush(title, body) {
-  const res = await fetch(`http://127.0.0.1:${GATEWAY_PORT}/pwa/push/send`, {
+// gatewayPort comes from the resolved config's `port` (default 3088).
+async function sendPush(title, body, gatewayPort) {
+  const res = await fetch(`http://127.0.0.1:${gatewayPort}/pwa/push/send`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ title, body: body || '' })
@@ -153,7 +142,10 @@ export function assistantText(message) {
 // Summary of the closing turn, from the session's append-only event log:
 // the LAST assistant message that produced real text, or — when the whole
 // turn was tool work with no prose — the last tool name. Never thinking text.
-export function turnSummary(events, turn) {
+// lang is the resolved language ('en' | 'zh'); omitted (tests, ad-hoc calls)
+// it falls back to DSH_PUSH_LANG, then Chinese.
+export function turnSummary(events, turn, lang) {
+  const copy = COPY[resolveLang(lang)]
   if (!Array.isArray(events)) return ''
   let lastTool = ''
   for (let i = events.length - 1; i >= 0; i--) {
@@ -168,7 +160,7 @@ export function turnSummary(events, turn) {
       lastTool = ev.data.name
     }
   }
-  return lastTool ? T.lastTool.replace('{tool}', lastTool) : ''
+  return lastTool ? copy.lastTool.replace('{tool}', lastTool) : ''
 }
 
 // First question of an ask_user_question call, from the raw (unparsed)
@@ -193,8 +185,7 @@ export function sessionEvents(session) {
   if (session && typeof session.snapshotEvents === 'function') {
     // ponytail: snapshotEvents() with no argument copies the WHOLE event log
     // on every call. That is acceptable here — this branch only runs when
-    // INCLUDE_SUMMARY is on (dsh-push.mjs:53, off by default) and at most once
-    // per turn end. Slicing would need the turn's start seq, and the
+    // includeSummary is on (off by default) and at most once per turn end. Slicing would need the turn's start seq, and the
     // agent/turn-stopping payload carries none: its emitter (0.1.2
     // dsh-agent-loop) sends only `{ turn, signal }` plus the injected
     // `agent` — a turn NUMBER, not an event-log seq, and the two are not the
@@ -217,10 +208,13 @@ const skip = (reason) => ({ shouldNotify: false, title: '', body: '', reason })
  *   summary         already-extracted turn summary  ('turn-end')
  *   toolName        tool awaiting approval          ('approval')
  *   question        pending question text           ('question')
- * @param {object} cfg { turnEndEnabled, debounceMs, includeSummary }
+ * @param {object} cfg { turnEndEnabled, debounceMs, includeSummary, lang }
+ *   lang is the resolved notification language ('en' | 'zh'); when absent
+ *   (policy tests build their own cfg) DSH_PUSH_LANG decides, else Chinese.
  * @returns {{shouldNotify: boolean, title: string, body: string, reason: string}}
  */
 export function decideNotification(input, cfg) {
+  const copy = COPY[resolveLang(cfg.lang)]
   const debounced = (input.now - input.lastSent) < cfg.debounceMs
 
   switch (input.kind) {
@@ -229,15 +223,15 @@ export function decideNotification(input, cfg) {
     case 'approval':
       return {
         shouldNotify: true,
-        title: T.approvalTitle,
-        body: input.toolName ? T.approvalBody.replace('{tool}', input.toolName) : T.approvalBodyPlain,
+        title: copy.approvalTitle,
+        body: input.toolName ? copy.approvalBody.replace('{tool}', input.toolName) : copy.approvalBodyPlain,
         reason: 'approval-pending'
       }
     case 'question':
       return {
         shouldNotify: true,
-        title: T.questionTitle,
-        body: (cfg.includeSummary && input.question) || T.questionBody,
+        title: copy.questionTitle,
+        body: (cfg.includeSummary && input.question) || copy.questionBody,
         reason: 'question-pending'
       }
 
@@ -246,7 +240,7 @@ export function decideNotification(input, cfg) {
       if (!cfg.turnEndEnabled) return skip('turn-end-disabled')
       if ((input.delegationDepth ?? 0) !== 0) return skip('subagent')
       if (debounced) return skip('debounced')
-      return { shouldNotify: true, title: T.turnEndTitle, body: input.summary || T.turnEndBody, reason: 'turn-end' }
+      return { shouldNotify: true, title: copy.turnEndTitle, body: input.summary || copy.turnEndBody, reason: 'turn-end' }
 
     default:
       return skip('unknown-kind')
@@ -298,9 +292,10 @@ const PUSH_TOOL_GLOBAL_MAX = 20
 
 // Registers the push_notify model tool against ctx.tools, if present and not
 // disabled. Throttle state lives in this closure (fresh per apply() call, so
-// tests get isolated state without needing a fresh module import).
-function registerPushTool(ctx, gate) {
-  if (!PUSH_TOOL_ENABLED) {
+// tests get isolated state without needing a fresh module import). Both the
+// enabled flag and the gateway port arrive from apply()'s resolved config.
+function registerPushTool(ctx, gate, pushToolEnabled, gatewayPort) {
+  if (!pushToolEnabled) {
     console.log('[dsh-zen-remote-push] push_notify disabled (DSH_PUSH_TOOL=0 / pushTool:false)')
     return
   }
@@ -310,7 +305,7 @@ function registerPushTool(ctx, gate) {
   // registered. inject() defers the callback until the service exists (the
   // same pattern vision-toolkit uses for webServer) and still degrades
   // gracefully: hosts without a tools service simply never fire it.
-  ctx.inject(['tools'], (toolsCtx) => registerPushToolWith(toolsCtx, toolsCtx.tools, gate))
+  ctx.inject(['tools'], (toolsCtx) => registerPushToolWith(toolsCtx, toolsCtx.tools, gate, gatewayPort))
 
   // Standing reinforcement of the same guidance. Order 150 is the documented
   // tool-guidance band (@deepseek-ai/dsh-system-prompt PromptSection.order).
@@ -325,7 +320,7 @@ function registerPushTool(ctx, gate) {
   })
 }
 
-function registerPushToolWith(ctx, tools, gate) {
+function registerPushToolWith(ctx, tools, gate, gatewayPort) {
   if (!tools) {
     console.log('[dsh-zen-remote-push] "tools" service not present — push_notify not registered')
     return
@@ -396,7 +391,7 @@ function registerPushToolWith(ctx, tools, gate) {
       // why it dropped a call.
       gate.arm(now)
       try {
-        const result = await sendPush(args.title, args.body)
+        const result = await sendPush(args.title, args.body, gatewayPort)
         return { delivered: (result && typeof result.sent === 'number') ? result.sent : 0 }
       } catch (e) {
         console.warn(`[dsh-zen-remote-push] push_notify send failed: ${String(e && e.message || e)}`)
@@ -409,8 +404,26 @@ function registerPushToolWith(ctx, tools, gate) {
 
 // ---------------------------------------------------------------------------
 
-export function apply(ctx) {
-  const cfg = { turnEndEnabled: TURN_END_ENABLED, debounceMs: DEBOUNCE_MS, includeSummary: INCLUDE_SUMMARY }
+export function apply(ctx, config) {
+  // The input is ALWAYS re-resolved, whatever it is: the main entry passes
+  // its already-resolved effective values (idempotent — legal values stay
+  // put), while an old-style standalone load passing `{}` or a partial row
+  // still gets env and lan-gate.config.json their say instead of being
+  // masked by whatever the object happened to contain. Precedence:
+  // env > row > lan-gate.config.json > defaults (src/config.ts).
+  const values = resolveConfig(config ?? {}, readFileConfig(), process.env).values
+  const gatewayPort = Number(values.port ?? 3088)
+  const events = String(values.pushEvents ?? 'agent/turn-stopping').split(',').map((s) => s.trim()).filter(Boolean)
+  const lang = resolveLang(values.lang)
+  // Legacy knob, deliberately outside the T12 config table: honored from
+  // env/file exactly as before so existing files keep working.
+  const graceMs = approvalPendingMs(readFileConfig())
+  const cfg = {
+    turnEndEnabled: values.pushTurnEnd === true,
+    debounceMs: Number(values.pushDebounceMs ?? 15000),
+    includeSummary: values.pushSummary === true,
+    lang
+  }
 
   // The one piece of mutable state: when the last push went out. Wrapped so
   // every leg runs the same pure decision and shares the same debounce clock.
@@ -426,7 +439,7 @@ export function apply(ctx) {
   const fire = (input) => {
     const decision = gate.decide(input)
     // Best-effort; never raise into the host.
-    if (decision.shouldNotify) sendPush(decision.title, decision.body).catch(() => {})
+    if (decision.shouldNotify) sendPush(decision.title, decision.body, gatewayPort).catch(() => {})
     return decision
   }
 
@@ -444,10 +457,10 @@ export function apply(ctx) {
     fire({
       kind: 'turn-end',
       delegationDepth: header && header.delegationDepth,
-      summary: INCLUDE_SUMMARY ? turnSummary(sessionEvents(session), payload && payload.turn) : ''
+      summary: cfg.includeSummary ? turnSummary(sessionEvents(session), payload && payload.turn, lang) : ''
     })
   }
-  for (const event of EVENTS) {
+  for (const event of events) {
     try {
       ctx.on(event, onTurnEnd)
     } catch (e) {
@@ -469,7 +482,7 @@ export function apply(ctx) {
         const timer = setTimeout(() => {
           armed.delete(id)
           fire({ kind: 'approval', toolName })
-        }, APPROVAL_PENDING_MS)
+        }, graceMs)
         if (typeof timer.unref === 'function') timer.unref()
         armed.set(id, timer)
       } else if (event.type === 'approval/decided') {
@@ -483,7 +496,7 @@ export function apply(ctx) {
     console.warn(`[dsh-zen-remote-push] cannot listen on "session/event": ${String(e && e.message || e)}`)
   }
 
-  console.log(`[dsh-zen-remote-push] approval/question notifications on (approval grace ${APPROVAL_PENDING_MS}ms); turn-end (${EVENTS.join(', ')}) ${TURN_END_ENABLED ? 'on' : 'off — set DSH_PUSH_TURN_END=1 to enable'}`)
+  console.log(`[dsh-zen-remote-push] approval/question notifications on (approval grace ${graceMs}ms); turn-end (${events.join(', ')}) ${cfg.turnEndEnabled ? 'on' : 'off — set DSH_PUSH_TURN_END=1 to enable'}`)
 
-  registerPushTool(ctx, gate)
+  registerPushTool(ctx, gate, values.pushTool !== false, gatewayPort)
 }