dsh-session-superagent 0.8.20 → 0.8.29

package/CHANGELOG.md

@@ -2,6 +2,174 @@
 
 格式参照 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.8.29] - 2026-11-02 —— `watch_doctor` 现在会告诉你「面板接口死没死」
+
+这一轮的真机事故（重复路由 → 六条接口全灭）有个共同特征：**工具还是好的，只有面板挂了**。
+`watch_status` 看不出异常，用户只会觉得"面板空白"。而 `state.server` 里其实一直记着挂载结果。
+
+### 新增
+`watch_doctor` 第一行现在是挂载状态：
+
+```
+OK   面板接口挂载：6 条，无失败
+FAIL 面板接口挂载：webserver: duplicate exact route "/session-superagent/state"（工具仍可用，但面板会空白；重载一次即可）
+WARN 面板接口部分失败（5/6 成功）：…
+```
+
+### 测试
+- 新增用例：doctor 输出里必须有挂载状态行。合计 **91 例**。
+  （写这个用例时踩到一个小坑：`cleanup` 用例会删掉临时状态目录，doctor 用例必须排在它前面 —— 否则看到的是"没有挂载记录"。）
+
+## [0.8.28] - 2026-11-02 —— 旧实例还在吃 HTTP 请求（面板建的 watcher 一开就废）
+
+### 真机复验发现
+宿主在 19:49 挂载成功（`routes: 6, failed: []`），但**通过 HTTP（面板）建的 watcher 仍然报**：
+
+```
+lastError: cannot get required service "agents" in inactive context
+consecutiveFailures: 0 / nextAt: None
+```
+
+对照实验：用**工具**（`watch_start`）建的 watcher 同一时刻轮询正常、无错误。
+差别在于请求被谁处理 —— 路由最初由 19:32 那个实例注册，重载后若没走 dispose，
+它继续吃 HTTP 请求，而它的 `ctx` 早已 dispose；于是那些 watcher 的定时器跑在死上下文里。
+
+### 修复
+模块级 `activeRoutes`：每次 `apply()` 注册路由前，**先摘掉上一次注册的**（接管而不是并存）。
+配合 0.8.25 的单条容错与 0.8.26 的 teardown，重载后的三条路径都覆盖了。
+
+### 测试
+- 新增用例：同一模块 `apply` 两次时，第二次会先 unregister 第一批（6 条）再注册新的 6 条。合计 **90 例**。
+
+## [0.8.27] - 2026-11-02 —— 文案核对 + 把 0.8.21–0.8.27 一次发到 npm
+
+### 文案
+- 「已添加，30 秒内开始轮询」不准确：`startWatcher()` 会**立刻**跑一次 tick（不等 30 秒的下限），
+  改成「已添加，首轮立即开始轮询」。
+
+### 发布
+- 一次把 0.8.21–0.8.27 发出去（npm 上原来停在 0.8.20）。已确认 `latest = 0.8.27`，
+  tarball 直装验证：`version 0.8.27`、`routes 6`、`client.js` 语法通过、新文案在位。这一批里有三个真机事故修复：
+  `inactive context`（唤醒会失败）、未预期异常不退避、热重载后重复路由导致面板全灭。
+
+### 测试
+- 合计 **89 例**。
+
+## [0.8.26] - 2026-11-02 —— 卸载时真的把路由摘掉（重复路由的根因）
+
+0.8.25 让「一条重复不再全灭」，这一版处理根因：**卸载时要把旧路由摘掉**，否则宿主重载后
+永远是新旧两套并存，面板读到的是旧 handler（改了密码却还是老数据那种感觉）。
+
+### 修复
+- 把清理逻辑抽成 `teardown()`，同时挂在 **`ctx.effect(() => teardown)`** 与 `ctx.on('dispose', …)` 两条路上：
+  effect 作用域销毁时一定调用，事件广播方式也能覆盖。`teardown()` 本身可重复调用（摘完就清空列表）。
+
+### 测试
+- 新增用例：卸载时六条路由都被 unregister；重复卸载不会重复 unregister。合计 **89 例**。
+
+## [0.8.25] - 2026-11-02 —— 热重载时一条重复路由会让**全部**接口消失
+
+### 真机现场
+```
+server = {at: 19:38:26Z, error: 'webserver: duplicate exact route "/session-superagent/state"'}
+```
+宿主热重载时，旧实例的路由还没被 dispose，新实例注册第一条就抛 —— 而注册是**一整块 try**，
+于是六条路由全军覆没，面板一片空白（数据接口全 404），只有重启才能恢复。
+
+### 修复
+每条路由改成单独容错（`addRoute()`）：重复的那条把原因记进 `state.server.failed`，
+其余照常注册。单条重复不再等于全站不可用。
+
+### 守门
+新增 `test/route-resilience.test.mjs`：让宿主替身在注册 `client-error` 时抛重复路由，
+断言其余 5 条仍然注册成功、`/state` 仍在、失败原因被记录下来。
+
+### 测试
+- 合计 **88 例**。
+
+## [0.8.24] - 2026-11-02 —— 安装说明是错的（`npm i` 不会让 DSH 加载插件）
+
+### 修复
+README 原来写「方式一：npm，`npm i dsh-session-superagent`」，但 **DSH 插件必须装进 profile**
+才会被加载（包里的 `dsh.bundle.patch` 由 profile 的安装流程读取）；`npm i` 只是下载到本地
+`node_modules`，什么都不会发生。另一条「`dsh plugin add < GitHub URL>`」本机也没有这个子命令。
+
+对照同机的其它插件（`dsh-unlag` 用 `dsh plugin install dsh-unlag`、
+`dsh-better-sidebar` 用 `dsh plugin --profile web add …@latest`）改成：
+
+```bash
+dsh plugin install dsh-session-superagent
+dsh plugin --profile desktop add dsh-session-superagent@latest
+dsh plugin install /path/to/dsh-session-superagent      # 本地开发
+```
+
+并写清「`npm i` 不会生效」与「装进 profile 后是硬链接、新增文件要 `sync:profile`」。
+
+### 测试
+- 合计 **87 例**。
+
+## [0.8.23] - 2026-11-02 —— README 补「故障排查」，并把链接到的文档发进包
+
+### 文档
+- README 新增**故障排查**表，全部来自真实事故：新增文件没进 profile 导致插件不挂载、
+  硬链接断了导致「改了但没生效」、`inactive context`、幽灵会话不退避、
+  npm 刚发布时的 `ETARGET`、以及「有动静但没被叫醒」该看哪里（`watch_status` 的 `deferred=`、面板的「最近被过滤」）。
+- README 底部链接的 `UPDATING.md` / `CHECKLIST.md` / `MAINTENANCE.md` 之前**不在 `files` 里**，
+  npm 页面上点了是 404。现在一起发出去（`npm pack` 10 → 13 个文件）。
+
+### 测试
+- 合计 **87 例**。
+
+## [0.8.22] - 2026-11-02 —— 未预期异常也要退避（0.8.21 的同一类问题再补一刀）
+
+0.8.21 修的是「读 `ctx.agents` 会抛」。修完回头看 tick 的兜底：
+
+```js
+} catch (error) {
+  entry.lastError = String(error.message)   // 只记错误
+}
+```
+
+也就是说 **任何**未预期异常都会让 watcher 按 `intervalSec` 无限重试 —— 正是 inactive-context
+那次的症状（`consecutiveFailures: 0`、`nextAt: None`）。现在 catch 里也 `bumpFailure(entry, every)`，
+坏掉的东西最多 30 分钟试一次，不会持续打 GitHub。
+
+### 说明
+这属于「同类问题系统性收口」，不是新功能：凡是走出 `pollOnce` 正常分支的失败，现在都会进退避窗口。
+
+### 测试
+- 合计 **87 例**（该分支需要真实定时器上下文，靠重载后的真机复验确认）。
+
+## [0.8.21] - 2026-11-02 —— 真机复验抓到的**唤醒致命 bug**：inactive context
+
+宿主重载后（`routes: 6`，0.8.14–0.8.20 全部生效）做了真机复验，造了一条绑定「不存在会话」的 watcher：
+
+```
+lastError: cannot get required service "agents" in inactive context
+consecutiveFailures: 0     ← 没进退避
+nextAt: None               ← 每 intervalSec 都会再打一次 GitHub
+```
+
+### 根因
+定时器回调跑在**非活跃上下文**里，直接读 `ctx.agents` 会抛错。读 `goals` 一直用的是
+`ctx.get('goals')`（不抛），唯独 `agents` 用的是 `ctx.agents` —— 这行代码在**每一次真唤醒**、
+每一次「会话还在不在」判断上都会执行。
+
+### 影响
+- 幽灵会话判断（0.8.11）在本机其实从没跑到过：轮询在更早的一行就抛了。
+- 更严重的是：**如果宿主对定时器上下文同样报错，真实唤醒也会失败**（看起来"在盯"，其实一次都没成）。
+
+### 修复
+新增 `agentsService(ctx)`：优先 `ctx.get('agents')`，取不到再兜底直接读；`wake()`、
+`pollOnce()` 与两个工具（`watch_start` / `watch_stop`）全部改走它。
+
+### 守门
+新增 `test/agents-context.test.mjs`：用一个**读 `ctx.agents` 就抛**的宿主替身，验证
+`watch_start` / `watch_status` 仍然正常，并断言不会把宿主的上下文错误当成轮询错误。这条路以前完全没测过。
+
+### 测试
+- 合计 **87 例**。
+
 ## [0.8.20] - 2026-11-02 —— 冷启动演练：工具返回要能证明「选项生效了」
 
 照 HANDOFF + README 走一遍「加 watcher → 观察 → 确认」（不看代码，只看文档），暴露的摩擦点：
@@ -16,6 +184,14 @@
   HTTP 只在面板/调试时用 —— 并写清端口每次重启都会变、怎么找（会话上下文里的 GUI URL 或按 PID 查 netstat）。
   冷启动演练时就是卡在「端口找不到」这一步。
 
+### 发布
+- 已发 `dsh-session-superagent@0.8.20`（一次性带上 0.8.17–0.8.20 的改动；`latest = 0.8.20`）。
+- tarball 直装验证：`version 0.8.20`、**routes 6**、`client.js` 语法通过、
+  包内只有 7 项（CHANGELOG/LICENSE/README/client.js/cordis.patch.yml/lib/package.json）。
+- **CI 已接入 `preflight --fast`**：GitHub Actions 在 Node 22 / 24 两个矩阵上跑
+  「单测 / 语法 / 版本一致 / 路由面 / 包内容」，本地无 profile 时该检查自动 SKIP。
+  运行记录：`gh run list` → `test (22)` 与 `test (24)` 均 success。
+
 ### 测试
 - 合计 **85 例**。
 
@@ -465,7 +641,7 @@ OK   .dsh-zhuli 下正好一个副本
 
 ## [0.8.0] - 2026-11-01 —— 移植官方 superagent 的 GUI
 
-把官方 `dsh-superagent`（D:\主工作区\projects\dsh-superagent-prototype）的**设计系统与信息架构**
+把官方 `dsh-superagent`（本地 checkout 的 dsh-superagent-prototype）的**设计系统与信息架构**
 搬进「主理鱼」标签页，数据接我们自己的 `/state`、`/watch`。
 
 ### 移植了什么
@@ -595,7 +771,7 @@ OK   .dsh-zhuli 下正好一个副本
 
 ### 修复
 - **中文路径被写成乱码**：Windows 下 argv 里的中文常是 GBK 字节，按 UTF-8 解得到一串 U+FFFD
-  （实测 `D:/主工作区/...` 存成 `D:/??????/...`，worktree 建不出来）。新增 `decodeBody()`：
+  （实测中文路径 `D:/某中文目录/...` 存成 `D:/??????/...`，worktree 建不出来）。新增 `decodeBody()`：
   UTF-8 解码出现替换字符就用 `TextDecoder('gbk')` 重解。
 - **同一个 watcher 并跑两轮**：首轮 tick 与手动「立刻」撞车会开两个隔离区。`entry.polling` 做并发闸，重复请求 409。
 - `/state` 补 `isolated` / `workdir` / `lastWorktree`。

package/CHECKLIST.md

@@ -0,0 +1,26 @@
+# CHECKLIST —— 两张表，两个交付门
+
+## A 表 · 代码交付前
+
+- [ ] `node --test` 全绿，且新增行为有测试
+- [ ] 所有返回字符串都过 `redact()`（新增输出路径重点查）
+- [ ] 写操作仍要求 `confirm: true`
+- [ ] 唤醒仍受 `agent.status === 'idle'` 约束
+- [ ] 唤醒失败时不推进水位（`entry.seen` 不动）
+- [ ] `package.json` 的 `files` 覆盖所有要发布的文件（`lib` + 文档 + patch）
+- [ ] 没有把本地路径、个人 token、机器名写进仓库
+
+## B 表 · 发版前
+
+- [ ] 从最新 `main` 起功能分支
+- [ ] `CHANGELOG.md` 增加条目，`package.json` bump 版本
+- [ ] 本地 `node --test` 通过
+- [ ] PR 合并到 `main`
+- [ ] 打 annotated tag `vX.Y.Z` 并推送
+- [ ] 创建 GitHub Release，说明取自 CHANGELOG
+- [ ] 安装验证：`dsh plugin --profile <p> add github:MYCF711/dsh-session-superagent`
+
+## 发完之后
+
+- [ ] 在测试仓库 `watch_start` 跑一轮，确认唤醒可达
+- [ ] 记录一次真实运行的观察结果到本仓库 issue

package/MAINTENANCE.md

@@ -0,0 +1,35 @@
+# MAINTENANCE —— 维护台账（给接手的 agent 看）
+
+## 一、身份
+
+- 包名：`dsh-session-superagent`
+- 形态：DSH 插件（tools-only + 自带 `cordis.patch.yml`）
+- 目标宿主：DeepSeek Harness ≥ 0.2.1-rc.5
+- 依赖：宿主已安装并登录 `gh` CLI；Node ≥ 22.19
+
+## 二、当前状态（2026-11-01）
+
+- [x] 七个工具可用（github / repo_here / watch_start / watch_status / watch_stop / watch_ack / watch_doctor），`node --test` 88/88 通过
+- [x] 自回声抑制（逐条水位）
+- [x] 仅空闲注入（避免草稿回放）
+- [x] 唤醒失败不推进水位
+- [ ] webhook 代替轮询（未做）
+- [ ] 多仓库单会话（未做，当前每会话一仓库）
+
+## 三、下一步
+
+1. 真实仓库连跑 24h，统计 `lastWake` 与误唤醒次数；
+2. 把 `trigger.json` 从正式包移出（或加开关），它只是测试通道；
+3. 评估 `steer()` 与 `followup()` 在不同场景下的取舍。
+
+## 四、硬约束
+
+1. **不注入正在运行的会话**——会污染客户端输入框，可能导致重复发送。
+2. **凭证永不出插件**：所有返回必须过 `redact()`；新增输出路径要补测试。
+3. **不改 profile 的 `bundles`**：那是操作者动作，包只带 patch。
+4. **不删除用户文件**；状态文件写失败必须静默降级。
+5. **没跑过的写成“未验证”**，不写“通过”。
+
+## 五、最短接手路径
+
+读 `README.md`（做什么）→ 本文件（现状与约束）→ `CHECKLIST.md`（交付门）→ `UPDATING.md`（怎么发版）→ `lib/watch.js`（核心逻辑，纯函数，测试齐全）。

package/README.md

@@ -1,7 +1,9 @@
 # dsh-session-superagent
 
+<img src="assets/icon-180.png" width="88" height="88" alt="">
+
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-0.8.20-green.svg)](https://github.com/MYCF711/dsh-session-superagent/releases)
+[![Version](https://img.shields.io/badge/version-0.8.29-green.svg)](https://github.com/MYCF711/dsh-session-superagent/releases)
 [![npm](https://img.shields.io/npm/v/dsh-session-superagent.svg)](https://www.npmjs.com/package/dsh-session-superagent)
 [![dsh](https://img.shields.io/badge/DeepSeek%20Harness-plugin-orange.svg)](https://github.com/topics/dsh-plugin)
 
@@ -51,15 +53,24 @@ GitHub 有新动态 → watcher 轮询 → Agent.followup(消息) → 会话跑
 
 ## 安装
 
+**装进 profile**（DSH 插件不是 `npm i` 就生效，要装到 profile 里）：
+
 ```bash
-# 方式一：npm（已发布）
-npm i dsh-session-superagent
+# 默认 profile
+dsh plugin install dsh-session-superagent
 
-# 方式二：从 GitHub 源码装（会跟踪 main）
-dsh plugin add https://github.com/MYCF711/dsh-session-superagent
+# 指定 profile / 锁定版本
+dsh plugin --profile desktop add dsh-session-superagent@latest
+
+# 本地开发：直接装这个目录（会以 file: 硬链接方式挂进 profile）
+dsh plugin install /path/to/dsh-session-superagent
 ```
 
-装进 profile 时是 `file:` 硬链接，改代码即改线上；**但新增文件不会被自动带过去**，
+> `npm i dsh-session-superagent` 只会把它下载到本地 node_modules，**不会**让 DSH 加载它 ——
+> 包里的 `dsh.bundle.patch` 要由 profile 的安装流程来读。
+> 也可以在应用内的插件市场里搜索安装。
+
+装进 profile 后是 `file:` 硬链接：改源码即改线上；**但新增文件不会被自动带过去**，
 加完文件要跑 `pnpm run sync:profile`（否则下次重启插件会整体不挂载，这坑踩过一次）。
 
 ## 一次真实运行长什么样
@@ -88,11 +99,24 @@ dsh plugin add https://github.com/MYCF711/dsh-session-superagent
 ## 开发
 
 ```sh
-node --test          # 85 项单测
+node --test          # 88 项单测
 ```
 
 版本与发布流程见 [UPDATING.md](UPDATING.md)，交付门见 [CHECKLIST.md](CHECKLIST.md)，接手台账见 [MAINTENANCE.md](MAINTENANCE.md)。
 
+## 故障排查（都是真实踩过的）
+
+| 症状 | 原因 | 处理 |
+|---|---|---|
+| 面板空白、`watch_*` 工具消失、`/session-superagent/*` 全 404 | 新增的 `lib/*.js` 没同步进 profile（`file:` 安装只对**已有**文件建硬链接），宿主 import 失败 → 整个插件不挂载 | `pnpm run sync:profile`，然后重载插件 |
+| 改了代码但线上行为没变 | 硬链接断了 —— **原子写、`git checkout/restore`、某些编辑器的保存**都会换 inode，profile 里还是旧文件 | `pnpm run sync:profile:check` 看漂移，`sync:profile:repair` 修 |
+| 轮询报 `cannot get required service "agents" in inactive context` | 0.8.21 之前的 bug：定时器里直接读 `ctx.agents` | 升级到 ≥0.8.21 |
+| 绑定的会话已删除，watcher 还在打 GitHub | 0.8.14 之前的 bug：该类失败没进退避 | 升级到 ≥0.8.14（0.8.22 起未预期异常也会退避） |
+| `npm i dsh-session-superagent@<新版本>` 报 `ETARGET` | 刚发布，npm 客户端元数据缓存还没刷新 | 等 1-2 分钟，或 `npm i <tarball URL>` / `--prefer-online` |
+| 有动静但会话没被叫醒 | 会话忙 / 时段外 / 每小时上限 / 被子过滤器刷掉 | `watch_status` 会显示 `deferred=` / `paused`；面板「总览」的「最近被过滤」给原因 |
+
+`pnpm run preflight` 一条命令可自查：单测、语法、profile 一致性、版本一致、路由面、包内容、冒烟。
+
 ## 许可
 
 MIT，见 [LICENSE](LICENSE)。

package/UPDATING.md

@@ -0,0 +1,43 @@
+# 更新与发布
+
+## 铁律
+
+默认分支只接受通过门禁的 PR；`main` 永远可安装。
+
+## 发一个版本
+
+```bash
+git checkout main && git pull
+git checkout -b feat/<主题>
+
+# 1) 改代码 + 补测试
+node --test
+
+# 2) bump 版本 + 写 CHANGELOG
+#    语义化：修 bug → patch；加能力 → minor；改默认行为/改 patch 行 id → major
+
+# 3) 提交并推分支
+git add -A && git commit -m "feat: ..."
+git push -u origin feat/<主题>
+
+# 4) PR 全绿后合并
+gh pr create --fill && gh pr merge --squash --delete-branch
+
+# 5) 回到 main 打 tag 并发 Release
+git checkout main && git pull
+git tag -a v0.1.1 -m "v0.1.1"
+git push origin v0.1.1
+gh release create v0.1.1 --title "v0.1.1" --notes-from-tag
+```
+
+## 用户怎么升级
+
+```bash
+dsh plugin --profile <p> update dsh-session-superagent
+```
+
+pnpm 依据 `github:` 规格重新解析；或重新 `add` 一次覆盖。
+
+## 兼容性
+
+插件依赖宿主内部 API（`ctx.tools`、`ctx.agents`）。升级到新的 DSH 内部 API 视为 **major**，因为旧宿主可能不再提供同样的服务。

package/client.js

@@ -14,7 +14,7 @@ window.__ModuleLoader__.load({
     const { useCallback, useEffect, useRef, useState } = React
 
     // 客户端版本探针：每次模块加载写一次，用来确认浏览器里跑的是哪一版
-    const CLIENT_VERSION = '0.8.20'
+    const CLIENT_VERSION = '0.8.29'
     const BASE = '/session-superagent'
     const ENDPOINT = BASE + '/state'
     const POLL_MS = 5000
@@ -739,7 +739,7 @@ window.__ModuleLoader__.load({
           }),
         })
         setForm({ repo: '', intervalSec: form.intervalSec, goal: '', labels: '', onlyAssigned: false, activeHours: form.activeHours, isolated: form.isolated, workdir: form.workdir, observe: form.observe })
-      }, '已添加，30 秒内开始轮询')
+      }, '已添加，首轮立即开始轮询')
 
       const saveCredentials = () => run(async () => {
         const payload = {}

package/lib/index.js

@@ -41,6 +41,15 @@ const TRIGGER_FILE = join(STATE_DIR, 'trigger.json')
 const CLIENT_NOTE_KEYS = new Set(['client-version', 'apply', 'desk-registered', 'desk-fail', 'orbit-registered', 'orbit-fail', 'orbit-mount', 'badge-registered', 'badge-mount', 'badge-state', 'error'])
 const DEFAULT_COOLDOWN_MS = 180_000
 
+/**
+ * 当前挂在这个进程上的路由 disposer。
+ * 宿主重载时若没走 dispose，旧实例会继续吃 HTTP 请求，而它的 ctx 可能已经 dispose ——
+ * 真机表现：面板建的 watcher 第一轮就报
+ * `cannot get required service "agents" in inactive context`（2026-11-02 复验）。
+ * 所以每次 apply 注册路由前，先把上一次的摘掉。
+ */
+const activeRoutes = []
+
 function readState() {
   try { return JSON.parse(readFileSync(STATE_FILE, 'utf8')) } catch { return { watchers: {} } }
 }
@@ -182,6 +191,22 @@ function ghEnv() {
   return { ...process.env, GH_TOKEN: String(s.token) }
 }
 
+/**
+ * 安全地取 agents 服务。
+ * 定时器回调跑在「非活跃上下文」里，直接读 `ctx.agents` 会抛
+ * `cannot get required service "agents" in inactive context`（2026-11-02 真机复验踩到）；
+ * `ctx.get(name)` 不抛，取不到就返回 undefined。
+ */
+function agentsService(ctx) {
+  try {
+    if (typeof ctx.get === 'function') {
+      const viaGet = ctx.get('agents')
+      if (viaGet) return viaGet
+    }
+  } catch {}
+  try { return ctx.agents } catch { return undefined }
+}
+
 /** gh CLI 可用性探针：5 分钟缓存，别让面板每 5 秒都 spawn 一次 gh。 */
 const ghHealthCache = { at: 0, value: null }
 async function ghHealth() {
@@ -339,7 +364,8 @@ function defineTool(options) {
  * inbox alone only parks the message (the client shows it as a pending draft).
  */
 function wake(ctx, sessionId, text) {
-  const agent = ctx.agents && typeof ctx.agents.get === 'function' ? ctx.agents.get(sessionId) : undefined
+  const agents = agentsService(ctx)
+  const agent = agents && typeof agents.get === 'function' ? agents.get(sessionId) : undefined
   if (!agent) return { ok: false, reason: 'session not live' }
 
   const allowed = decideWake(agent.status)
@@ -468,7 +494,8 @@ async function pollOnce(ctx, entry, baseMs) {
     return
   }
   // 会话忙就别开隔离区了：白建一个没人用的 worktree
-  const liveAgent = ctx.agents && typeof ctx.agents.get === 'function' ? ctx.agents.get(entry.sessionId) : undefined
+  const liveAgents = agentsService(ctx)
+  const liveAgent = liveAgents && typeof liveAgents.get === 'function' ? liveAgents.get(entry.sessionId) : undefined
   if (!liveAgent) {
     // 会话已经不在了（被删/换机器）：别开隔离区，也别假装在盯。
     // 必须走 bumpFailure —— 否则这条会每 intervalSec 打一次 GitHub，永不退避（第四轮审核指出）。
@@ -540,7 +567,10 @@ export function apply(ctx) {
       try {
         await pollOnce(ctx, entry, every)
       } catch (error) {
+        // 未预期的异常（比如宿主上下文/服务不可用）也必须退避：
+        // 之前只写 lastError，于是坏掉的 watcher 会按 intervalSec 无限重试（真机踩到过）。
         entry.lastError = String((error && error.message) || error)
+        bumpFailure(entry, every)
       } finally {
         inFlight.delete(entry.id)
         persistEntry(entry)
@@ -568,7 +598,22 @@ export function apply(ctx) {
   // does not wait for it.
   const registerRoutes = (httpServer) => {
     if (!httpServer || typeof httpServer.register !== 'function') return
+    for (const dispose of activeRoutes) { try { dispose() } catch {} }
+    activeRoutes.length = 0
     const routes = []
+    // 宿主热重载时旧实例的路由可能还没 dispose；一条重复会让整个 try 崩掉，
+    // 面板和所有接口一起 404（2026-11-02 真机踩到 webserver: duplicate exact route）。
+    // 改成每条路由单独容错：重复的那条记下来，其余照常注册。
+    const failedRoutes = []
+    const addRoute = (options) => {
+      try {
+        const dispose = httpServer['register'](options)
+        routes.push(dispose)
+        activeRoutes.push(dispose)
+      } catch (error) {
+        failedRoutes.push(String((error && error.message) || error).slice(0, 120))
+      }
+    }
     const record = (kind, detail) => {
       const state = readState()
       state.client = state.client || {}
@@ -576,7 +621,7 @@ export function apply(ctx) {
       writeState(state)
     }
     try {
-      routes.push(httpServer.register({
+      addRoute({
         kind: 'exact',
         path: '/session-superagent/state',
         handler: async (req, res) => {
@@ -627,8 +672,8 @@ export function apply(ctx) {
             watchers: watchers.map((w) => ({ ...w, goal: goalView(ctx, w.sessionId) })),
           }))
         },
-      }))
-      routes.push(httpServer.register({
+      })
+      addRoute({
         kind: 'exact',
         path: '/session-superagent/client-note',
         handler: (req, res) => {
@@ -640,12 +685,12 @@ export function apply(ctx) {
           }
           res.statusCode = 204; res.end()
         },
-      }))
-      routes.push(httpServer.register({
+      })
+      addRoute({
         kind: 'exact',
         path: '/session-superagent/client-error',
         handler: (req, res) => { record('error', String(req.url).slice(0, 400)); res.statusCode = 204; res.end() },
-      }))
+      })
       const readBody = (req) => new Promise((resolve) => {
         const chunks = []
         req.on('data', (chunk) => chunks.push(chunk))
@@ -666,7 +711,7 @@ export function apply(ctx) {
 
       // Create or update a watcher from the panel. The panel is session-scoped,
       // so it must send the session id it is bound to.
-      routes.push(httpServer.register({
+      addRoute({
         kind: 'exact',
         path: '/session-superagent/watch',
         handler: async (req, res) => {
@@ -747,11 +792,11 @@ export function apply(ctx) {
           }
           json(res, 200, { ok: true, id, repo, intervalSec, enabled: entry.enabled })
         },
-      }))
+      })
 
       // Credentials typed by the operator. Stored 0600 under the state dir and
       // never echoed back; the answer carries only a masked summary.
-      routes.push(httpServer.register({
+      addRoute({
         kind: 'exact',
         path: '/session-superagent/credentials',
         handler: async (req, res) => {
@@ -775,12 +820,12 @@ export function apply(ctx) {
           writeSecrets(next)
           json(res, 200, { credentials: secretsSummary() })
         },
-      }))
+      })
 
       // Set / edit / clear the session's REAL goal through ctx.goals — the same
       // service the /goal command drives, so the panel and the conversation are
       // one source of truth (polling reads it back).
-      routes.push(httpServer.register({
+      addRoute({
         kind: 'exact',
         path: '/session-superagent/goal',
         handler: async (req, res) => {
@@ -812,23 +857,30 @@ export function apply(ctx) {
             return json(res, 400, { error: String((error && error.message) || error) })
           }
         },
-      }))
+      })
 
       const state = readState()
-      state.server = { at: new Date().toISOString(), routes: routes.length }
+      state.server = { at: new Date().toISOString(), routes: routes.length, failed: failedRoutes }
       writeState(state)
     } catch (error) {
       const state = readState()
-      state.server = { at: new Date().toISOString(), error: String((error && error.message) || error).slice(0, 300) }
+      state.server = { at: new Date().toISOString(), routes: routes.length, failed: failedRoutes, error: String((error && error.message) || error).slice(0, 300) }
       writeState(state)
     }
-    ctx.on('dispose', () => {
+    const teardown = () => {
       for (const dispose of routes) { try { dispose() } catch {} }
+      routes.length = 0
+      activeRoutes.length = 0
       // 插件卸载/热重载后旧定时器不能继续跑：它们还持有已 dispose 的 ctx
       for (const handle of timers.values()) { try { clearInterval(handle) } catch {} }
       timers.clear()
       try { clearInterval(sweepHandle) } catch {}
-    })
+    }
+    // 两条路都挂上：ctx.effect 的清理函数在 effect 作用域销毁时一定被调用；
+    // ctx.on('dispose') 覆盖宿主走事件广播的卸载方式。真机踩过「路由没 dispose →
+    // 重载后重复路由 → 六条接口全灭」，多挂一条成本很低。
+    try { ctx.effect(() => teardown) } catch {}
+    ctx.on('dispose', teardown)
   }
 
   // Routes for the panel. `webServer` is the host's route registry (the same
@@ -934,6 +986,22 @@ export function apply(ctx) {
       const all = Object.values(state.watchers || {})
       const wanted = args.repo ? all.filter((w) => w && w.repo === String(args.repo)) : all
 
+      // 0. 挂载状态：面板/HTTP 靠路由，路由注册失败时工具仍然可用 —— 这种「半死」状态
+      //    光看工具是发现不了的（2026-11-02 真机踩过：duplicate exact route 让六条接口全灭）
+      if (state.server) {
+        const mounted = Number(state.server.routes) || 0
+        const failed = Array.isArray(state.server.failed) ? state.server.failed : []
+        if (state.server.error) {
+          lines.push(`FAIL 面板接口挂载：${state.server.error}（工具仍可用，但面板会空白；重载一次即可）`)
+        } else if (failed.length > 0) {
+          lines.push(`WARN 面板接口部分失败（${mounted}/6 成功）：${failed.join('；')}`)
+        } else {
+          lines.push(`OK   面板接口挂载：${mounted} 条，无失败`)
+        }
+      } else {
+        lines.push('WARN 还没有挂载记录（刚装上或从未加载过路由）')
+      }
+
       // 1. gh 是否登录
       const auth = await run('gh', ['auth', 'status'], { env: ghEnv() })
       const authed = auth.code === 0
@@ -1032,7 +1100,8 @@ export function apply(ctx) {
       goal: { type: 'string', description: 'Optional per-watcher goal appended to the wake message.' },
     },
     async execute(args) {
-      const agent = ctx.agents && typeof ctx.agents.currentInitiator === 'function' ? ctx.agents.currentInitiator() : undefined
+      const toolAgents = agentsService(ctx)
+      const agent = toolAgents && typeof toolAgents.currentInitiator === 'function' ? toolAgents.currentInitiator() : undefined
       const sessionId = agent && agent.id
       if (!sessionId) return '[error: no live session — watch_start must be called from a session turn]'
 
@@ -1135,7 +1204,8 @@ export function apply(ctx) {
     description: 'Stop watching a repository for the current session.',
     parameters: { repo: { type: 'string', required: true, description: 'owner/name' } },
     async execute(args) {
-      const agent = ctx.agents && typeof ctx.agents.currentInitiator === 'function' ? ctx.agents.currentInitiator() : undefined
+      const toolAgents = agentsService(ctx)
+      const agent = toolAgents && typeof toolAgents.currentInitiator === 'function' ? toolAgents.currentInitiator() : undefined
       const sessionId = agent && agent.id
       const id = `${args.repo}#${sessionId}`
       const state = readState()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-session-superagent",
-  "version": "0.8.20",
+  "version": "0.8.29",
   "description": "Session-level superagent for DeepSeek Harness: watch a GitHub repository and wake a session when something needs doing. Credentials never reach the model.",
   "type": "module",
   "main": "lib/index.js",
@@ -17,7 +17,10 @@
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
-    "client.js"
+    "client.js",
+    "UPDATING.md",
+    "CHECKLIST.md",
+    "MAINTENANCE.md"
   ],
   "engines": {
     "node": ">=22.19.0",