dsh-turn-recovery 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,231 +1,286 @@
-# Changelog
-
-本文件记录 dsh-turn-recovery 的所有重要变更，格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
-版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
-
-> **改名说明（0.2.0）**：本插件原名 `dsh-empty-turn-guard`，因与另外两个同名项目（`FYTXY/dsh-empty-turn-guard`、
-> `@nlflora/dsh-empty-turn-guard`）冲突，自 0.2.0 起更名为 `dsh-turn-recovery`。0.1.x 及更早的条目保留旧名原文，
-> 其提到的 `plugin:empty-turn-guard`、`empty-turn-guard.log` 等标识在 0.2.0 起分别改为 `plugin:turn-recovery`、`turn-recovery.log`。
-
-## [0.2.0] - 2026-11-01
-
-**更名发布**，功能与 0.1.6 完全一致，不含行为变化。
-
-### 变更
-
-- npm 包名 `dsh-empty-turn-guard` → **`dsh-turn-recovery`**；GitHub 仓库同步更名。
-- 运行时插件 id `empty-turn-guard` → **`turn-recovery`**（`export const name`、`dsh.bundle.patch` 的 `- id:`、profile 里覆盖用的 `- id:` 全部随之改变）。
-- 补写消息来源 `plugin:empty-turn-guard` → **`plugin:turn-recovery`**。
-- 系统提示段落名 `empty-turn-guard` → **`turn-recovery`**（`order` 仍为 960）。
-- 日志文件名 `empty-turn-guard.log` → **`turn-recovery.log`**。
-- 版本号从 0.1.6 跳到 0.2.0：包名与插件 id 都是破坏性变更（旧的 profile 注册与 `node_modules` 链接必须更新，否则宿主会静默跳过该 bundle），按语义化版本应当断代。
-
-### 升级须知
-
-从 0.1.x 升级需要同时改三处，缺一处宿主要么静默不加载、要么加载旧目录：
-
-1. profile 的 `dependencies` 与 `dsh.profile.bundles` 里的包名；
-2. profile 的 `cordis.patch.yml` 里 `- id: empty-turn-guard` → `- id: turn-recovery`（配置内容不变）；
-3. `node_modules` 里的包链接（junction）需要重建为新包名。
-
-旧日志文件 `~/.dsh/logs/empty-turn-guard.log` 不会自动改名，可以保留作历史，也可以直接删除。
-
-
-修复第四轮复核（DSH `0.2.1-rc.5`）确认的两个**独立状态机缺陷**，以及用户点停止不可观察、
-日志/配置层面的若干小问题。`lib/index.js` 的判定口径没变，改的都是「状态什么时候被清/被置」。
-
-### 修复
-
-- **P2-A 认领不校验消息 id（中）**：`user/message` 只要 `source.kind = 'plugin:empty-turn-guard'`
-  就置 `awaitingGuardTurn = true`，而 `matched` 只写进日志。于是上次进程遗留、重放、或另一实例
-  写入的同来源消息会被当成「补写回合」，让下一个**真正的**空回合被 `stop chaining` 静默跳过。
-  现在只有 id 与在途补写一致才置位，不一致记 `NOT ours` 并忽略。
-- **P2-B 缺少数值 turn 的 turn/end 不清状态（中）**：早退分支在 `wasGuard` 取值与清零之前
-  `return`，`awaitingGuardTurn` 永久留在 `true`。现在先取后清，再判断 turn 是否可判定。
-  （当前宿主唯一 emitter 恒给 number，属潜伏缺陷，用 mock 可复现。）
-- **P2-C 用户点停止不可观察（低，缓解）**：宿主 `cancel()` 只清 inbox + abort，不发 session 事件，
-  900ms 窗口内仍会补写。现在订阅宿主的 `agent/inbox/discarded`，**只**在丢弃的正是我们那条
-  补写时才撤标记；宿主不广播该事件时退回旧行为，不会误伤。
-- **日志轮转更鲁棒（低）**：Windows 上多进程持句柄时 `rename` 会 EPERM/EBUSY，现在回退
-  `truncate(0)` 并记一条日志（宁可丢历史，也不让日志无限长）。
-- **agent 注册表对账（低）**：除 `agent/disposed` 外，注册表每增长 20 条向宿主 `agents.list()`
-  对账一次，删掉已消失的条目。
-- **会话过滤留痕（低）**：`sessionScope='root'` 过滤掉的会话每个 id 记一条 `skip scope` 日志，
-  「插件没加载」与「被 scope 静默过滤」不再长得一样。
-- **激活日志带版本号**：`plugin activated: pid=… version=…`，版本从自身 `package.json` 读，
-  不再需要靠「某字段是否存在」推断进程里跑的是哪一版。
-- **`instructionText` 上限 4000 字符**：它进每回合 system prompt，超长会长期抬高输入 token。
-
-### 测试
-
-- `test/guard.test.mjs` 28 → **34 条**：新增 P2-A（id 不符不吞下一回合）、P2-B（缺 turn 也清状态）、
-  P2-C（丢弃自己那条 → 释放在途标记；丢弃别人的 → 不动）、激活日志版本号、`skip scope` 只记一次、
-  `instructionText` 截断。
-- 修了测试夹具的一处失真：`guardClaim()` 过去不带 id，无法表达「认领」。
-
-## [0.1.5] - 2026-10-29
-
-修复桌面端 / 网页端复核发现的状态机与来源分类问题。
-
-### 修复
-
-- **投递 ≠ 认领（中）**：`awaitingGuardTurn` 过去在 `agent.send()` 成功时就置位，但 send 只是把消息放进
-  `next-turn` 队列；消息在认领前可能被用户停止/会话取消清掉，下一次真正的空回合会被当成「连环补写」
-  跳过。现在投递成功只记录 `nudgeMessageId`（在途），只有转录里出现 `source.kind =
-  'plugin:empty-turn-guard'` 的 `user/message`（被宿主认领）才置位 `awaitingGuardTurn`。在途补写 120 秒
-  未被认领视为过期；上一笔未认领前不再排第二笔。
-- **后台来源白名单覆盖最新宿主（中）**：新增 `agent-instructions` / `ptc-mode` / `model-selection` /
-  `session-reference` / `skill-invocation` / `compact-checkpoint`。这些是宿主或插件写入的上下文/状态消息，
-  不是有人在说话；旧白名单会把它们当插话，取消待发补写。
-- **文档口径**：README 的附件判定改为「助手消息含附件不算空」；补充 `dsh headless` 一次性进程的限制；
-  更新 2026-10-29 的实测样本。
-
-### 测试
-
-- `test/guard.test.mjs` 从 27 条扩到 **28 条**：新增「投递 ≠ 认领」用例；后台注入用例覆盖最新宿主的
-  6 个来源；预算/连环补写用例改为显式模拟宿主认领。
-
-### 验证
-
-- 用真实 DSH `0.2.1-rc.3` 宿主 + 假模型做端到端验证：turn 1 返回 ZWSP → 插件 `nudge DELIVERED` →
-  turn 2 出现 `plugin:empty-turn-guard` 的 `user/message` → 模型返回可见正文，`wasGuard=true`。
-  桌面端生产日志仍未遇到 `completed` 空回合，链路已由 e2e 覆盖。
-
-## [0.1.4] - 2026-10-29
-
-修复第三轮评审（技术方案评审团：架构 / 应用安全 / 现实核对）确认的缺陷。核心是**空回合判定本身**：
-0.1.3 之前漏判「UI 空白但 `visibleChars >= 1`」的回合，而那正是本插件唯一要救的场景。
-
-### 修复
-
-- **零宽集改用 Unicode 属性（高）**：0.1.3 的手写码位清单漏了 `U+2066–U+2069`（双向隔离符）、`U+E0001`、
-  `U+E0020–U+E007F`（tag 字符）、`U+1D173–U+1D17A`（音乐控制符）——这些字符渲染为空白却被计成正文，
-  回合因此不补写。现在改用 `\p{Default_Ignorable_Code_Point}` 并补 `U+2800`/`U+3164`/`U+FFA0` 三个
-  不属于 DI 的填充符，实测不误伤中文/英文/数字/标点。
-- **`inject` 假投递（高）**：`agent.inject(m)` 实际是 `send(m, 'next-step', false)`——**不唤醒**，
-  消息躺在 next-step 队列里等下一个回合认领。旧实现把它当第三级兜底，于是日志写 `DELIVERED`、
-  `awaitingGuardTurn` 置 `true`，却没有任何新回合发生，下一次真空回合还会被当成「连环补写」跳过。
-  0.1.4 起只保留会唤醒的 `send(next-turn, wakeup)` 与等价的 `followup`，全部失败就明确记 `NOT DELIVERED`。
-- **热重载中途误判（中）**：0.1.3 去掉了 `assistantMessages > 0` 门槛后，插件在回合中途加载/热重载时
-  看不到该回合早前的助手消息，`visibleChars = 0` 会被当成空回合而发假提醒。新增 `sawTurnStart`，
-  没见过 `turn/start` 的回合一律不判定（日志 `turn/start not observed`）。
-- **日志 tag 恒定（中）**：根会话 id 形如 `session-<uuid>`，`id.slice(0, 8)` 恒为 `session-`，多会话无法区分。
-  现在先剥 `session-` 前缀再取 8 位。
-- **图片附件回合误判（低）**：只有 `image` / `file` / `attachment` / `audio` / `video` 的回合在界面上并非空白，
-  不再判空（`tool-call`、`reasoning` 仍按空回合处理）。
-- **`turn` 缺失（低）**：`turn/end` 没有数值 `turn` 时直接跳过判定（旧实现拿 `s.turn` 兜底，两者都为 `null`
-  会命中 `guardSentForTurn === turn` 而静默跳过）。
-- **会话范围（低）**：默认只处理根会话（`/^session-/`）。子代理会话（裸 UUID）「只调工具不回正文」是正常收尾，
-  社交桥会话（`social-*`）也不是空回合，都不再补写。需要旧行为可设 `sessionScope: 'all'`。
-- **插话判定（低）**：`runtime-context` / `time-context` / `skill-catalog` / `dsh-mnemon` 与 `plugin:*`
-  视为背景注入，不取消待发补写；其余来源（真人、子代理回报、微信/社交桥）都取消。
-- **兜底日志不轮转（低）**：`maybeRotate` 现在对主路径和 `os.tmpdir()` 兜底路径都生效，轮转前显式删除旧 `.1`
-  （避免 Windows 上覆盖失败）。
-- **`engines.dsh` 加上界**：`>=0.2.1-rc.1 <0.3.0`。原来没有上界，将来 0.3.0 起 API 若变，插件会静默加载失败或行为异常。
-
-### 测试
-
-- `test/guard.test.mjs` 从 19 条扩到 **27 条**。新增：中途加载不判定、图片附件不判空、`turn` 缺失、
-  会话范围（root/all）、后台注入不取消 / 社交桥取消、只有 `inject` 可用时不算投递成功、
-  DI 码位（`U+2066`/`U+E0020`/`U+1D173`/`U+E0100`/`U+FFA0`）、日志 tag 剥前缀。
-
-### 已知未解
-
-- 补写消息仍以 `role:'user'` 落进持久转录（`source.kind = 'plugin:empty-turn-guard'`）。宿主
-  `dsh-session` 对 `source.kind` 无枚举校验，桌面 UI 会把非 `user` 来源渲染成 `kind:'context'` 的上下文块
-  而非用户气泡，但转录层面它仍是一条 user 消息——插件侧无法改 `role`，只能靠 `source` 标注。
-- 生产环境至今 **0 次**真实补写投递（日志 `nudge DELIVERED` 为 0），链路正确性仍缺一次端到端演练。
-
-## [0.1.3] - 2026-10-26
-
-修复评审（技术方案评审团：架构 / 应用安全 / 现实核对）发现的缺陷，重点是空回合补写的状态机。
-
-### 修复
-
-- **补写状态机（高）**：`awaitingGuardTurn` 在三条早退路径上不清零——真人插话取消、补写回合非 `completed`（`aborted` / `error` / `max-tokens`）、三级投递全失败——导致**下一次真正的空回合被误判成「连环补写」而静默跳过**，日志还写 `stop chaining`。现在 `turn/end` 入口先取 `wasGuard` 再无条件清零；投递失败也显式清零。
-- **`runtime-context` 被当成真人插话（中）**：宿主每一步都会 append 一条 `source.kind === 'runtime-context'` 的 `user/message`（`dsh-agent-loop`），旧实现把所有非本插件的 `user/message` 都当成真人取消补写，实际上补写几乎必被取消。现在只有 `source.kind === 'user'`（`source` 缺失时保守视为真人）才取消。
-- **小时预算被取消操作吃掉（中）**：旧实现「调度即记账」，取消/失败也占额度；现在按**投递成功**记账。
-- **零宽字符集过窄（中）**：补上 `U+3164`（韩文填充符，最常被当作「隐形字」）、`U+2800`（盲文空白）、`U+180B–U+180E`、`U+FE00–U+FE0F`、`U+2065`、`U+206A–U+206F`、`U+FFA0`、`U+E0100–U+E01EF`、`U+034F`、`U+061C`、`U+115F`、`U+1160`、`U+17B4`、`U+17B5`、`U+2028`、`U+2029` 等。
-- **配置语义**：`maxNudgesPerHour: 0` 现在真的关闭补写（旧实现被 `|| 3` 吞成 3）；`delayMs: "abc"` 等非法值回落默认值（旧实现 `|| 0` 变成 0 毫秒）；`enabled: "false"` 字符串现在真的关闭（旧实现只认布尔 `false`）。
-- **回合竞态**：空回合结束后 900ms 内若新回合自己起来，旧实现会把补写插进别人的回合；现在 `turn/start` 取消过期定时器，定时器触发时再校验 `pendingTurn` 是否仍等于当前回合。
-- **漏判**：没有任何 `assistant/message` 的 `completed` 回合（`visibleChars === 0`）旧实现因为 `assistantMessages > 0` 前置条件而漏判，现在会补写。
-- **热启用惰性**：旧实现只靠 `agent/created` 填 agent 表，插件热启用时存量会话永远没有 agent、补写全被 `SKIPPED`。现在启动时向宿主 `agents` 注册表 `list()` 回填一次。
-- **日志**：跟随 `DSH_HOME`（旧实现硬编码 `os.homedir()`）、超过 5 MB 自动轮转、每行带会话 id 前 8 位与 `wasGuard`。
-
-### 变更
-
-- 补写消息正文不再要求模型「不要提及这条提醒」：该消息以 `role:'user'` 落进持久转录，隐瞒来源属于破坏转录完整性。现在明确写「插件自动补发」，并带 `source = { kind: 'plugin:empty-turn-guard', plugin, reason }`。
-
-### 测试
-
-- `test/guard.test.mjs` 从 9 条扩到 **19 条**（此处原写「18 条」有误），并修正**事件载荷形状**：宿主 `session.append(type, data)` 的 `data` 就是消息本体（`data.source.kind`），旧用例包了一层 `{ message: { source } }`，导致「真人插话取消」「plugin 来源不参与判定」两条用例实际空转。新增：非 completed 后不污染下一回合、投递全失败后可恢复、`runtime-context` 不取消、新回合丢弃过期补写、配置 0/非法值语义、扩展零宽集、热启用回填、卸载清理。
-
-### 明确不做
-
-- `inject = ['systemPrompt']` 保持硬依赖。本版本 `@deepseek-ai/cordis` 的 `Inject.resolve` 只接受数组或「name → config 映射」，**没有 `required`/`optional` 语义**；改成 `{ optional: [...] }` 会被当成「等一个叫 optional 的服务」，插件永不激活。
-
-## [0.1.2] - 2026-10-25
-
-放宽宿主版本门槛：功能无改动。
-
-### 变更
-
-- `engines.dsh` 从 `>=0.2.1-rc.2` 放宽到 `>=0.2.1-rc.1`。
-  依据：本插件用到的宿主 API（`ctx.systemPrompt.section`、`agent.send` / `followup` / `inject`、
-  `agent/created`、`session/event`、`dsh.bundle.patch` 加载）在 DSH `0.2.1-rc.1` / `rc.2` / `rc.3`
-  三个版本的实现**逐字节相同**（`dsh-system-prompt`、`dsh-agent-loop`、`dsh-agent`、`dsh-session`、
-  `dsh-app-boot`、`dsh-plugin-manager`、`dsh-web-app` 的 `lib/index.js` md5 三版本一致，差异仅在
-  `package.json` 的版本号字段）。所以 rc.1 上代码本来就能跑，旧门槛只是把它挡在门外——
-  宿主 `dsh-app-boot` 的版本闸门不满足时会把 bundle 收进 `skippedBundles`，启动只打一行
-  `dsh: skipping profile bundle "dsh-empty-turn-guard": …` 然后**静默不加载**。
-
-### 注意
-
-- **不要**把范围写成 `>=0.2.1`。semver 规则里预发布版本不满足「不含预发布标识的同段范围」，
-  `0.2.1-rc.3` 对 `>=0.2.1` 判为 `false`，那样会把 rc.1 / rc.2 / rc.3 全部挡掉。
-
-## [0.1.1] - 2026-10-25
-
-发布规范化版本：功能与 0.1.0 一致，补齐工程与元数据。
-
-### 新增
-
-- `test/guard.test.mjs`：9 条契约测试，用 mock ctx 驱动真实 `apply()`，不依赖宿主即可回归。
-  覆盖零宽空回合补写、正常回合不干预、非 `completed` 不补写、补写回合再空不连环、
-  真人插话取消、`send` 失败降级 `followup`、`plugin:` 来源消息不参与判定。
-- `scripts/check-metadata.mjs`：发布前元数据检查，校验字段齐全、`files` 路径真实存在、
-  无 `TODO` 占位符、`cordis.patch.yml` 的 `- insert:` 与包名对齐、入口可 `import`。
-- `CHANGELOG.md`（本文件）。
-
-### 修正
-
-- 重新统计并修正 README 里的实测样本数据（原 0.1.0 写的是 738 回合 / 102 空 / 13.8%，
-  该口径把只有工具调用的步骤也算成了空回合）。准确口径：208 会话 / 766 回合，
-  可见正文为空的回合 39 个（5.1%），其中 `completed` 的 8 个（1.2%）才是本插件处理的对象。
-
-### 变更
-
-- `package.json` 补齐发布元数据：`repository` / `homepage` / `bugs` / `author` / `exports` /
-  `engines` / `publishConfig` / `scripts`。
-- `prepublishOnly` 串联 `check-metadata` 与 `test`，检查不过不允许发布。
-
-## [0.1.0] - 2026-10-25
-
-首个可用版本。
-
-### 新增
-
-- **C 空回合保护**：监听 `session/event`，在 `turn/end`（`reason.kind === 'completed'`）时
-  累计本回合所有 `assistant/message` 的可见正文；去掉零宽字符后为空则自动排一条
-  `target: 'next-turn'` 的补写消息（`agent.send(msg, 'next-turn', true)`，
-  失败依次降级 `followup` → `inject`），让模型在下一回合补出正文。
-- **A 收尾指令注入**：通过 `systemPrompt.section({ name, order: 960, interpolate: false })`
-  注入 222 字指令，要求每回合以看得见的正文收尾、禁止用零宽字符或空白充当回答。
-- 防误伤：同回合最多补写一次、补写回合再空即停、每小时最多 3 次、
-  定时器触发前收到真人消息立即取消、`plugin:` 来源消息不参与判定。
-- 日志落 `~/.dsh/logs/empty-turn-guard.log`，主路径不可写时兜底到系统临时目录。
-
-### 说明
-
-- 修复目标问题：模型把输出预算烧在 reasoning 上、正文只返回一个 `U+200B`，
-  而 DSH 的 `EMPTY_RESPONSE` 判空因「文本非空」不触发，回合被记为 `completed` 但界面空白。
+# Changelog
+
+本文件记录 dsh-turn-recovery 的所有重要变更，格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+> **改名说明（0.2.0）**：本插件原名 `dsh-empty-turn-guard`，因与另外两个同名项目（`FYTXY/dsh-empty-turn-guard`、
+> `@nlflora/dsh-empty-turn-guard`）冲突，自 0.2.0 起更名为 `dsh-turn-recovery`。0.1.x 及更早的条目保留旧名原文，
+> 其提到的 `plugin:empty-turn-guard`、`empty-turn-guard.log` 等标识在 0.2.0 起分别改为 `plugin:turn-recovery`、`turn-recovery.log`。
+
+## [0.2.1] - 2026-11-03
+
+**适配性修复**：针对 DSH `0.2.2-alpha.3` 实测（宿主 `dsh-session` / `dsh-agent-loop` /
+`dsh-system-prompt` / `dsh-app-boot` 源码取证 + 本机 37 个会话日志复核）。不含新功能，
+但有三处行为变化，升级前请读。
+
+### 修复
+
+- **会话范围改按 `SessionHeader` 判定**（原 `lib/index.js` 用 `/^session-/` 猜 id 前缀）：
+  只有 `header.origin === 'subagent'` 或 `header.delegationDepth > 0` 才算子代理会话。
+  0.2.0 把 `orchestrator-*` 这类顶层会话全部当成子代理过滤掉，实测日志里有 19 条
+  `skip scope: non-root session orchestrator` —— 通过路由器（orchestrator 会话）跑的
+  主对话从来没被保护过。宿主没有 header 时（老宿主 / 测试桩）退回 id 形态判定。
+- **取消策略由「后台黑名单」改为「前台白名单」**：默认只有 `source.kind === 'user'`
+  与 `'agent-message'` 会取消待发补写，且 `source.form === 'notice'` 永远不取消。
+  0.2.0 的黑名单没收录宿主后来新增的 `tool-jobs` / `action-cards` / `plan-mode` /
+  `tool-goal`（都是 `form: "notice"`）与 `goal` / `schedule` 自动化来源，它们会让
+  已排好的补写被静默取消。未知来源现在一律按后台处理，漏取消由 `turn/start`
+  分支兜底；自定义桥接可继续用 `foregroundKinds` 加回取消语义。
+- **prompt 段落注册失败改为 fail-closed**：宿主对同名 section 重复注册会直接 throw
+  （同一插件被两个 bundle 各装一次就会这样）。旧版 catch 之后仍打印 `guard armed`，
+  于是「222 字符收尾指令其实没进 prompt」在日志里看不出来，且两个实例会各发一条补写。
+  现在记 `guard NOT armed (fail-closed: ...)` 并整体不启用。
+- **投放前查宿主队列去重**：`nudgeMessageId` 是进程内记忆，重启 / 热重载 / 双实例时为空。
+  投递前检查 `agent.inbox.nextTurn` 里是否已有 `plugin:turn-recovery` 来源的待认领消息，
+  有则跳过，避免同一个空回合被连投两笔。
+- **小时预算跨重启生效**：投递时刻追加到 `$DSH_HOME/state/turn-recovery/nudges.log`，
+  进程启动后首次见到某会话时回读最近一小时。旧版的 `nudgeTimes` 只在内存里，重启即清零，
+  同一会话每次重启都能重新领满额度。
+- **`engines.dsh` 上界收紧为 `<0.3.0-0`**：宿主用 `semver` 的 `includePrerelease: true`
+  判定门槛，`<0.3.0` 会放行 `0.3.0-alpha.1` / `0.3.0-beta.2`（实测为 true）。`-0` 是显式的
+  预发布截断。`scripts/check-metadata.mjs` 新增规则强制上界必须写成 `x.y.z-0`。
+- **日志可读性**：`guard armed` 现在带 `instruction=registered|disabled`；`skip scope`
+  带上判定依据（`header says subagent` / `id is not a root shape`）；`tag()` 同时剥掉
+  `orchestrator-` 前缀（否则所有 orchestrator 会话在日志里都显示成 `[orchestr]`）。
+- **日志行内的换行被压平**：会话 id、错误文本里带 `\n` 时可以伪造出一行看似插件自己
+  写的记录（例如假的 `guard armed` 或 `turn/end`），现在一律替换为空格。
+
+### 新增配置
+
+- `foregroundKinds: string[]`：追加「会取消待发补写」的来源 `kind`（默认 `user` / `agent-message`）。
+- `budgetFile: string`：补写预算的持久化路径（默认 `$DSH_HOME/state/turn-recovery/nudges.log`）。
+
+### 已知边界（不变，仅补文档）
+
+- 可见字符按**回合累计**而非末条消息计：先写结论、后被工具调用打断的回合不算空。
+- 非 `completed` 回合（`aborted` / `interrupted` / `error` / `max-tokens` / `blocked`）一律不补写。
+- `minVisibleChars` 默认 1 是刻意取最小阈值；要「短于 N 字也算空」可自行调高。
+
+### 验证
+
+- `node test/guard.test.mjs`：43 个用例全通过（新增 9 个：header 判根、notice 不取消、
+  前台白名单、`fail-closed`、inbox 去重、跨重启限流、预算落盘、`foregroundKinds`、日志压平）。
+- `node scripts/check-metadata.mjs`：通过；负向验证把上界改回 `<0.3.0` 会失败。
+
+## [0.2.0] - 2026-11-01
+
+**更名发布**，功能与 0.1.6 完全一致，不含行为变化。
+
+### 变更
+
+- npm 包名 `dsh-empty-turn-guard` → **`dsh-turn-recovery`**；GitHub 仓库同步更名。
+- 运行时插件 id `empty-turn-guard` → **`turn-recovery`**（`export const name`、`dsh.bundle.patch` 的 `- id:`、profile 里覆盖用的 `- id:` 全部随之改变）。
+- 补写消息来源 `plugin:empty-turn-guard` → **`plugin:turn-recovery`**。
+- 系统提示段落名 `empty-turn-guard` → **`turn-recovery`**（`order` 仍为 960）。
+- 日志文件名 `empty-turn-guard.log` → **`turn-recovery.log`**。
+- 版本号从 0.1.6 跳到 0.2.0：包名与插件 id 都是破坏性变更（旧的 profile 注册与 `node_modules` 链接必须更新，否则宿主会静默跳过该 bundle），按语义化版本应当断代。
+
+### 升级须知
+
+从 0.1.x 升级需要同时改三处，缺一处宿主要么静默不加载、要么加载旧目录：
+
+1. profile 的 `dependencies` 与 `dsh.profile.bundles` 里的包名；
+2. profile 的 `cordis.patch.yml` 里 `- id: empty-turn-guard` → `- id: turn-recovery`（配置内容不变）；
+3. `node_modules` 里的包链接（junction）需要重建为新包名。
+
+旧日志文件 `~/.dsh/logs/empty-turn-guard.log` 不会自动改名，可以保留作历史，也可以直接删除。
+
+
+修复第四轮复核（DSH `0.2.1-rc.5`）确认的两个**独立状态机缺陷**，以及用户点停止不可观察、
+日志/配置层面的若干小问题。`lib/index.js` 的判定口径没变，改的都是「状态什么时候被清/被置」。
+
+### 修复
+
+- **P2-A 认领不校验消息 id（中）**：`user/message` 只要 `source.kind = 'plugin:empty-turn-guard'`
+  就置 `awaitingGuardTurn = true`，而 `matched` 只写进日志。于是上次进程遗留、重放、或另一实例
+  写入的同来源消息会被当成「补写回合」，让下一个**真正的**空回合被 `stop chaining` 静默跳过。
+  现在只有 id 与在途补写一致才置位，不一致记 `NOT ours` 并忽略。
+- **P2-B 缺少数值 turn 的 turn/end 不清状态（中）**：早退分支在 `wasGuard` 取值与清零之前
+  `return`，`awaitingGuardTurn` 永久留在 `true`。现在先取后清，再判断 turn 是否可判定。
+  （当前宿主唯一 emitter 恒给 number，属潜伏缺陷，用 mock 可复现。）
+- **P2-C 用户点停止不可观察（低，缓解）**：宿主 `cancel()` 只清 inbox + abort，不发 session 事件，
+  900ms 窗口内仍会补写。现在订阅宿主的 `agent/inbox/discarded`，**只**在丢弃的正是我们那条
+  补写时才撤标记；宿主不广播该事件时退回旧行为，不会误伤。
+- **日志轮转更鲁棒（低）**：Windows 上多进程持句柄时 `rename` 会 EPERM/EBUSY，现在回退
+  `truncate(0)` 并记一条日志（宁可丢历史，也不让日志无限长）。
+- **agent 注册表对账（低）**：除 `agent/disposed` 外，注册表每增长 20 条向宿主 `agents.list()`
+  对账一次，删掉已消失的条目。
+- **会话过滤留痕（低）**：`sessionScope='root'` 过滤掉的会话每个 id 记一条 `skip scope` 日志，
+  「插件没加载」与「被 scope 静默过滤」不再长得一样。
+- **激活日志带版本号**：`plugin activated: pid=… version=…`，版本从自身 `package.json` 读，
+  不再需要靠「某字段是否存在」推断进程里跑的是哪一版。
+- **`instructionText` 上限 4000 字符**：它进每回合 system prompt，超长会长期抬高输入 token。
+
+### 测试
+
+- `test/guard.test.mjs` 28 → **34 条**：新增 P2-A（id 不符不吞下一回合）、P2-B（缺 turn 也清状态）、
+  P2-C（丢弃自己那条 → 释放在途标记；丢弃别人的 → 不动）、激活日志版本号、`skip scope` 只记一次、
+  `instructionText` 截断。
+- 修了测试夹具的一处失真：`guardClaim()` 过去不带 id，无法表达「认领」。
+
+## [0.1.5] - 2026-10-29
+
+修复桌面端 / 网页端复核发现的状态机与来源分类问题。
+
+### 修复
+
+- **投递 ≠ 认领（中）**：`awaitingGuardTurn` 过去在 `agent.send()` 成功时就置位，但 send 只是把消息放进
+  `next-turn` 队列；消息在认领前可能被用户停止/会话取消清掉，下一次真正的空回合会被当成「连环补写」
+  跳过。现在投递成功只记录 `nudgeMessageId`（在途），只有转录里出现 `source.kind =
+  'plugin:empty-turn-guard'` 的 `user/message`（被宿主认领）才置位 `awaitingGuardTurn`。在途补写 120 秒
+  未被认领视为过期；上一笔未认领前不再排第二笔。
+- **后台来源白名单覆盖最新宿主（中）**：新增 `agent-instructions` / `ptc-mode` / `model-selection` /
+  `session-reference` / `skill-invocation` / `compact-checkpoint`。这些是宿主或插件写入的上下文/状态消息，
+  不是有人在说话；旧白名单会把它们当插话，取消待发补写。
+- **文档口径**：README 的附件判定改为「助手消息含附件不算空」；补充 `dsh headless` 一次性进程的限制；
+  更新 2026-10-29 的实测样本。
+
+### 测试
+
+- `test/guard.test.mjs` 从 27 条扩到 **28 条**：新增「投递 ≠ 认领」用例；后台注入用例覆盖最新宿主的
+  6 个来源；预算/连环补写用例改为显式模拟宿主认领。
+
+### 验证
+
+- 用真实 DSH `0.2.1-rc.3` 宿主 + 假模型做端到端验证：turn 1 返回 ZWSP → 插件 `nudge DELIVERED` →
+  turn 2 出现 `plugin:empty-turn-guard` 的 `user/message` → 模型返回可见正文，`wasGuard=true`。
+  桌面端生产日志仍未遇到 `completed` 空回合，链路已由 e2e 覆盖。
+
+## [0.1.4] - 2026-10-29
+
+修复第三轮评审（技术方案评审团：架构 / 应用安全 / 现实核对）确认的缺陷。核心是**空回合判定本身**：
+0.1.3 之前漏判「UI 空白但 `visibleChars >= 1`」的回合，而那正是本插件唯一要救的场景。
+
+### 修复
+
+- **零宽集改用 Unicode 属性（高）**：0.1.3 的手写码位清单漏了 `U+2066–U+2069`（双向隔离符）、`U+E0001`、
+  `U+E0020–U+E007F`（tag 字符）、`U+1D173–U+1D17A`（音乐控制符）——这些字符渲染为空白却被计成正文，
+  回合因此不补写。现在改用 `\p{Default_Ignorable_Code_Point}` 并补 `U+2800`/`U+3164`/`U+FFA0` 三个
+  不属于 DI 的填充符，实测不误伤中文/英文/数字/标点。
+- **`inject` 假投递（高）**：`agent.inject(m)` 实际是 `send(m, 'next-step', false)`——**不唤醒**，
+  消息躺在 next-step 队列里等下一个回合认领。旧实现把它当第三级兜底，于是日志写 `DELIVERED`、
+  `awaitingGuardTurn` 置 `true`，却没有任何新回合发生，下一次真空回合还会被当成「连环补写」跳过。
+  0.1.4 起只保留会唤醒的 `send(next-turn, wakeup)` 与等价的 `followup`，全部失败就明确记 `NOT DELIVERED`。
+- **热重载中途误判（中）**：0.1.3 去掉了 `assistantMessages > 0` 门槛后，插件在回合中途加载/热重载时
+  看不到该回合早前的助手消息，`visibleChars = 0` 会被当成空回合而发假提醒。新增 `sawTurnStart`，
+  没见过 `turn/start` 的回合一律不判定（日志 `turn/start not observed`）。
+- **日志 tag 恒定（中）**：根会话 id 形如 `session-<uuid>`，`id.slice(0, 8)` 恒为 `session-`，多会话无法区分。
+  现在先剥 `session-` 前缀再取 8 位。
+- **图片附件回合误判（低）**：只有 `image` / `file` / `attachment` / `audio` / `video` 的回合在界面上并非空白，
+  不再判空（`tool-call`、`reasoning` 仍按空回合处理）。
+- **`turn` 缺失（低）**：`turn/end` 没有数值 `turn` 时直接跳过判定（旧实现拿 `s.turn` 兜底，两者都为 `null`
+  会命中 `guardSentForTurn === turn` 而静默跳过）。
+- **会话范围（低）**：默认只处理根会话（`/^session-/`）。子代理会话（裸 UUID）「只调工具不回正文」是正常收尾，
+  社交桥会话（`social-*`）也不是空回合，都不再补写。需要旧行为可设 `sessionScope: 'all'`。
+- **插话判定（低）**：`runtime-context` / `time-context` / `skill-catalog` / `dsh-mnemon` 与 `plugin:*`
+  视为背景注入，不取消待发补写；其余来源（真人、子代理回报、微信/社交桥）都取消。
+- **兜底日志不轮转（低）**：`maybeRotate` 现在对主路径和 `os.tmpdir()` 兜底路径都生效，轮转前显式删除旧 `.1`
+  （避免 Windows 上覆盖失败）。
+- **`engines.dsh` 加上界**：`>=0.2.1-rc.1 <0.3.0`。原来没有上界，将来 0.3.0 起 API 若变，插件会静默加载失败或行为异常。
+
+### 测试
+
+- `test/guard.test.mjs` 从 19 条扩到 **27 条**。新增：中途加载不判定、图片附件不判空、`turn` 缺失、
+  会话范围（root/all）、后台注入不取消 / 社交桥取消、只有 `inject` 可用时不算投递成功、
+  DI 码位（`U+2066`/`U+E0020`/`U+1D173`/`U+E0100`/`U+FFA0`）、日志 tag 剥前缀。
+
+### 已知未解
+
+- 补写消息仍以 `role:'user'` 落进持久转录（`source.kind = 'plugin:empty-turn-guard'`）。宿主
+  `dsh-session` 对 `source.kind` 无枚举校验，桌面 UI 会把非 `user` 来源渲染成 `kind:'context'` 的上下文块
+  而非用户气泡，但转录层面它仍是一条 user 消息——插件侧无法改 `role`，只能靠 `source` 标注。
+- 生产环境至今 **0 次**真实补写投递（日志 `nudge DELIVERED` 为 0），链路正确性仍缺一次端到端演练。
+
+## [0.1.3] - 2026-10-26
+
+修复评审（技术方案评审团：架构 / 应用安全 / 现实核对）发现的缺陷，重点是空回合补写的状态机。
+
+### 修复
+
+- **补写状态机（高）**：`awaitingGuardTurn` 在三条早退路径上不清零——真人插话取消、补写回合非 `completed`（`aborted` / `error` / `max-tokens`）、三级投递全失败——导致**下一次真正的空回合被误判成「连环补写」而静默跳过**，日志还写 `stop chaining`。现在 `turn/end` 入口先取 `wasGuard` 再无条件清零；投递失败也显式清零。
+- **`runtime-context` 被当成真人插话（中）**：宿主每一步都会 append 一条 `source.kind === 'runtime-context'` 的 `user/message`（`dsh-agent-loop`），旧实现把所有非本插件的 `user/message` 都当成真人取消补写，实际上补写几乎必被取消。现在只有 `source.kind === 'user'`（`source` 缺失时保守视为真人）才取消。
+- **小时预算被取消操作吃掉（中）**：旧实现「调度即记账」，取消/失败也占额度；现在按**投递成功**记账。
+- **零宽字符集过窄（中）**：补上 `U+3164`（韩文填充符，最常被当作「隐形字」）、`U+2800`（盲文空白）、`U+180B–U+180E`、`U+FE00–U+FE0F`、`U+2065`、`U+206A–U+206F`、`U+FFA0`、`U+E0100–U+E01EF`、`U+034F`、`U+061C`、`U+115F`、`U+1160`、`U+17B4`、`U+17B5`、`U+2028`、`U+2029` 等。
+- **配置语义**：`maxNudgesPerHour: 0` 现在真的关闭补写（旧实现被 `|| 3` 吞成 3）；`delayMs: "abc"` 等非法值回落默认值（旧实现 `|| 0` 变成 0 毫秒）；`enabled: "false"` 字符串现在真的关闭（旧实现只认布尔 `false`）。
+- **回合竞态**：空回合结束后 900ms 内若新回合自己起来，旧实现会把补写插进别人的回合；现在 `turn/start` 取消过期定时器，定时器触发时再校验 `pendingTurn` 是否仍等于当前回合。
+- **漏判**：没有任何 `assistant/message` 的 `completed` 回合（`visibleChars === 0`）旧实现因为 `assistantMessages > 0` 前置条件而漏判，现在会补写。
+- **热启用惰性**：旧实现只靠 `agent/created` 填 agent 表，插件热启用时存量会话永远没有 agent、补写全被 `SKIPPED`。现在启动时向宿主 `agents` 注册表 `list()` 回填一次。
+- **日志**：跟随 `DSH_HOME`（旧实现硬编码 `os.homedir()`）、超过 5 MB 自动轮转、每行带会话 id 前 8 位与 `wasGuard`。
+
+### 变更
+
+- 补写消息正文不再要求模型「不要提及这条提醒」：该消息以 `role:'user'` 落进持久转录，隐瞒来源属于破坏转录完整性。现在明确写「插件自动补发」，并带 `source = { kind: 'plugin:empty-turn-guard', plugin, reason }`。
+
+### 测试
+
+- `test/guard.test.mjs` 从 9 条扩到 **19 条**（此处原写「18 条」有误），并修正**事件载荷形状**：宿主 `session.append(type, data)` 的 `data` 就是消息本体（`data.source.kind`），旧用例包了一层 `{ message: { source } }`，导致「真人插话取消」「plugin 来源不参与判定」两条用例实际空转。新增：非 completed 后不污染下一回合、投递全失败后可恢复、`runtime-context` 不取消、新回合丢弃过期补写、配置 0/非法值语义、扩展零宽集、热启用回填、卸载清理。
+
+### 明确不做
+
+- `inject = ['systemPrompt']` 保持硬依赖。本版本 `@deepseek-ai/cordis` 的 `Inject.resolve` 只接受数组或「name → config 映射」，**没有 `required`/`optional` 语义**；改成 `{ optional: [...] }` 会被当成「等一个叫 optional 的服务」，插件永不激活。
+
+## [0.1.2] - 2026-10-25
+
+放宽宿主版本门槛：功能无改动。
+
+### 变更
+
+- `engines.dsh` 从 `>=0.2.1-rc.2` 放宽到 `>=0.2.1-rc.1`。
+  依据：本插件用到的宿主 API（`ctx.systemPrompt.section`、`agent.send` / `followup` / `inject`、
+  `agent/created`、`session/event`、`dsh.bundle.patch` 加载）在 DSH `0.2.1-rc.1` / `rc.2` / `rc.3`
+  三个版本的实现**逐字节相同**（`dsh-system-prompt`、`dsh-agent-loop`、`dsh-agent`、`dsh-session`、
+  `dsh-app-boot`、`dsh-plugin-manager`、`dsh-web-app` 的 `lib/index.js` md5 三版本一致，差异仅在
+  `package.json` 的版本号字段）。所以 rc.1 上代码本来就能跑，旧门槛只是把它挡在门外——
+  宿主 `dsh-app-boot` 的版本闸门不满足时会把 bundle 收进 `skippedBundles`，启动只打一行
+  `dsh: skipping profile bundle "dsh-empty-turn-guard": …` 然后**静默不加载**。
+
+### 注意
+
+- **不要**把范围写成 `>=0.2.1`。semver 规则里预发布版本不满足「不含预发布标识的同段范围」，
+  `0.2.1-rc.3` 对 `>=0.2.1` 判为 `false`，那样会把 rc.1 / rc.2 / rc.3 全部挡掉。
+
+## [0.1.1] - 2026-10-25
+
+发布规范化版本：功能与 0.1.0 一致，补齐工程与元数据。
+
+### 新增
+
+- `test/guard.test.mjs`：9 条契约测试，用 mock ctx 驱动真实 `apply()`，不依赖宿主即可回归。
+  覆盖零宽空回合补写、正常回合不干预、非 `completed` 不补写、补写回合再空不连环、
+  真人插话取消、`send` 失败降级 `followup`、`plugin:` 来源消息不参与判定。
+- `scripts/check-metadata.mjs`：发布前元数据检查，校验字段齐全、`files` 路径真实存在、
+  无 `TODO` 占位符、`cordis.patch.yml` 的 `- insert:` 与包名对齐、入口可 `import`。
+- `CHANGELOG.md`（本文件）。
+
+### 修正
+
+- 重新统计并修正 README 里的实测样本数据（原 0.1.0 写的是 738 回合 / 102 空 / 13.8%，
+  该口径把只有工具调用的步骤也算成了空回合）。准确口径：208 会话 / 766 回合，
+  可见正文为空的回合 39 个（5.1%），其中 `completed` 的 8 个（1.2%）才是本插件处理的对象。
+
+### 变更
+
+- `package.json` 补齐发布元数据：`repository` / `homepage` / `bugs` / `author` / `exports` /
+  `engines` / `publishConfig` / `scripts`。
+- `prepublishOnly` 串联 `check-metadata` 与 `test`，检查不过不允许发布。
+
+## [0.1.0] - 2026-10-25
+
+首个可用版本。
+
+### 新增
+
+- **C 空回合保护**：监听 `session/event`，在 `turn/end`（`reason.kind === 'completed'`）时
+  累计本回合所有 `assistant/message` 的可见正文；去掉零宽字符后为空则自动排一条
+  `target: 'next-turn'` 的补写消息（`agent.send(msg, 'next-turn', true)`，
+  失败依次降级 `followup` → `inject`），让模型在下一回合补出正文。
+- **A 收尾指令注入**：通过 `systemPrompt.section({ name, order: 960, interpolate: false })`
+  注入 222 字指令，要求每回合以看得见的正文收尾、禁止用零宽字符或空白充当回答。
+- 防误伤：同回合最多补写一次、补写回合再空即停、每小时最多 3 次、
+  定时器触发前收到真人消息立即取消、`plugin:` 来源消息不参与判定。
+- 日志落 `~/.dsh/logs/empty-turn-guard.log`，主路径不可写时兜底到系统临时目录。
+
+### 说明
+
+- 修复目标问题：模型把输出预算烧在 reasoning 上、正文只返回一个 `U+200B`，
+  而 DSH 的 `EMPTY_RESPONSE` 判空因「文本非空」不触发，回合被记为 `completed` 但界面空白。

package/README.md

@@ -15,9 +15,9 @@
 ## 行为
 
 1. **检测**：累计本回合所有 `assistant/message` 的 text 块，剥掉不可见字符后 trim。不可见集合用 Unicode 属性 `\p{Default_Ignorable_Code_Point}`（覆盖 `U+00AD / U+034F / U+061C / U+115F / U+1160 / U+17B4 / U+17B5 / U+180B–U+180E / U+200B–U+200F / U+202A–U+202E / U+2060–U+206F / U+FE00–U+FE0F / U+FEFF / U+E0001 / U+E0020–U+E007F / U+E0100–U+E01EF / U+1D173–U+1D17A` 等全部「默认可忽略」码位），再补三个渲染为空的填充符 `U+2800 / U+3164 / U+FFA0` 与行段分隔符 `U+2028 / U+2029`。`turn/end` 时若「可见字符数 < minVisibleChars 且 reason.kind === 'completed'」，判定为空回合 —— **没有任何 assistant 消息的 completed 回合也算空**（0 < 1）。助手消息含图片/文件/音视频附件时该回合不算空（界面上不是空白）；用户消息里的附件不计入这个判定。
-2. **补写**：延迟 `delayMs` 后通过 `agent.send(msg, 'next-turn', true)` 排一条 `plugin:turn-recovery` 来源的消息，让模型在下一回合补结论；`send` 抛错时降级到 `agent.followup(msg)`（与前者等价，都是唤醒并开新回合）。**不再使用 `agent.inject`**：它是 `send(msg, 'next-step', false)`，不唤醒，消息只会躺在队列里，旧版据此记 `DELIVERED` 属于假成功。消息正文明确写出「插件自动补发」，不自称普通用户输入。投递成功后只记「在途」并保存消息 id；只有宿主持久转录里出现该来源的 `user/message`（被认领）时，随后的回合才被视为补写回合。投递成功但 120 秒内未被认领视为过期，不阻塞下一次补写；上一笔补写未被认领前不会再排第二笔。
+2. **补写**：延迟 `delayMs` 后通过 `agent.send(msg, 'next-turn', true)` 排一条 `plugin:turn-recovery` 来源的消息，让模型在下一回合补结论；`send` 抛错时降级到 `agent.followup(msg)`（与前者等价，都是唤醒并开新回合）。**不再使用 `agent.inject`**：它是 `send(msg, 'next-step', false)`，不唤醒，消息只会躺在队列里，旧版据此记 `DELIVERED` 属于假成功。消息正文明确写出「插件自动补发」，不自称普通用户输入。投递成功后只记「在途」并保存消息 id；只有宿主持久转录里出现该来源的 `user/message`（被认领）时，随后的回合才被视为补写回合。投递前还会查宿主自己的 `agent.inbox.nextTurn`：队列里已经躺着一笔本插件的补写时不再投第二笔（内存标记在重启/双实例下会丢，队列不会）。投递成功但 120 秒内未被认领视为过期，不阻塞下一次补写；上一笔补写未被认领前不会再排第二笔。
 3. **收尾指令**：注册一段 system prompt（name `turn-recovery`，order 960，`interpolate: false`），要求每回合以看得见的正文结束、禁止用零宽字符/空白/空行充当回答。
-4. **防误伤**：同一回合最多补一次；补写回合再空则停止连环；每会话每小时最多 `maxNudgesPerHour` 次（按**投递成功**计，取消/失败不占额度）；定时器未触发前收到**有人说话**的消息（真人、子代理回报、微信/社交桥）立即取消，宿主的背景注入（`runtime-context` / `time-context` / `skill-catalog` / `dsh-mnemon` / `agent-instructions` / `ptc-mode` / `model-selection` / `session-reference` / `skill-invocation` / `compact-checkpoint` / `plugin:*`）不算；新回合自己起来时丢弃过期补写；`plugin:turn-recovery` 来源的消息不参与判定；插件在回合中途加载（没见过 `turn/start`）时不判定该回合。
+4. **防误伤**：同一回合最多补一次；补写回合再空则停止连环；每会话每小时最多 `maxNudgesPerHour` 次（按**投递成功**计，取消/失败不占额度，计数落盘到 `$DSH_HOME/state/turn-recovery/nudges.log`，**重启后仍然有效**）；定时器未触发前只有**明确有人在说话**的来源才取消补写 —— 默认是 `user`（真人输入）与 `agent-message`（agent 间转交），可用 `foregroundKinds` 追加自定义桥接；其余一切（宿主的 `runtime-context` / `time-context` / `skill-catalog` / `dsh-mnemon` 等自动上下文、`form: "notice"` 的工具/卡片/计划/任务通知、`goal` / `schedule` 自动化回合、`plugin:*`、以及**本插件不认识的新来源**）都按后台处理、不取消 —— 漏取消由「新回合自己起来」分支兜底；新回合自己起来时丢弃过期补写；`plugin:turn-recovery` 来源的消息不参与判定；插件在回合中途加载（没见过 `turn/start`）时不判定该回合。
 
 非 `completed` 的回合（`interrupted` / `error` / `aborted` / `max-tokens` / `blocked`）一律不补写。
 
@@ -31,7 +31,7 @@
 // <DSH_HOME>/profiles/<你的 profile>/package.json
 {
   "dependencies": {
-    "dsh-turn-recovery": "^0.2.0"
+    "dsh-turn-recovery": "^0.2.1"
   },
   "dsh": {
     "profile": {
@@ -62,7 +62,9 @@
     minVisibleChars: 1       # 可见字符数下限（<1 按 1 处理）
     delayMs: 900             # 补写前等待（毫秒，0–60000，非法值回落 900）
     maxNudgesPerHour: 3      # 每会话每小时的补写上限（0 = 关闭补写）
-    sessionScope: root       # root = 只处理根会话（session-*）；all = 连子代理/社交桥会话一起
+    sessionScope: root       # root = 只处理根会话（按 SessionHeader 判定）；all = 连子代理会话一起
+    foregroundKinds: []      # 追加「会取消待发补写」的来源 kind（默认 user / agent-message）
+    budgetFile: ''           # 空 = <DSH_HOME>/state/turn-recovery/nudges.log（跨重启限流）
     logFile: ''              # 空 = <DSH_HOME>/logs/turn-recovery.log
 ```
 
@@ -75,7 +77,7 @@
 ```
 [2026-10-25T01:49:13.941Z] plugin activated: pid=17520 enabled=true instruction=true dshHome=C:\Users\me\.dsh
 [2026-10-25T01:49:13.942Z] prompt section registered: order=960 chars=222
-[2026-10-25T01:49:13.942Z] guard armed (uptime=1ms)
+[2026-10-25T01:49:13.942Z] guard armed (instruction=registered, uptime=1ms)
 [2026-10-25T01:58:02.114Z] turn/end turn=3 kind=completed steps=4 visibleChars=812 empty=false wasGuard=false sawStart=true [5f884825]
 [2026-10-25T02:03:41.507Z] turn/end turn=4 kind=completed steps=6 visibleChars=0 empty=true wasGuard=false sawStart=true [5f884825]
 [2026-10-25T02:03:41.508Z] nudge SCHEDULED turn=4 delay=900ms [5f884825] (empty completed turn)
@@ -87,22 +89,23 @@
 
 `version=` 是进程里真正加载的版本号（从包自身 `package.json` 读）——**升级后先看这一行**，不要靠「某个日志字段有没有」推断跑的是哪一版（0.1.4 与 0.1.5 都打过 `sawStart`，这个推断会错）。
 
-排查常用短语：`skip scope`（被 `sessionScope` 过滤掉的会话）、`turn/start not observed`（热加载中途，不判定）、`NOT ours`（同来源但 id 对不上，已忽略）、`DISCARDED by host`（用户停止，补写被丢弃）、`a nudge is already awaiting claim`（上一笔还没被认领）、`stop chaining`（补写回合又空，按设计不再连环）、`budget exhausted`（本小时额度用完）。
+排查常用短语：`skip scope`（被 `sessionScope` 过滤掉的会话，括号里写明是 `header says subagent` 还是 `id is not a root shape`）、`guard NOT armed (fail-closed`（同名 prompt 段落已被占用，插件整体不启用，不再谎报 armed）、`inbox already holds a pending turn-recovery nudge`（队列里已有一笔，未重复投递）、`turn/start not observed`（热加载中途，不判定）、`NOT ours`（同来源但 id 对不上，已忽略）、`DISCARDED by host`（用户停止，补写被丢弃）、`a nudge is already awaiting claim`（上一笔还没被认领）、`stop chaining`（补写回合又空，按设计不再连环）、`budget exhausted`（本小时额度用完）。
 
 ## 实现约束
 
 - 只 import Node 内置模块（`node:fs` / `node:os` / `node:path` / `node:crypto`）。插件被装进 profile 的 `node_modules` 后，裸名 `@deepseek-ai/*` 在插件目录下 Node 解析不到，少一个依赖就少一个「插件整个加载失败」的风险面。
 - 不导出 `Config` schema（宿主允许无 schema 的 entry），配置在 `apply(ctx, config)` 内部做防御性默认值合并。
 - 所有逻辑包在 try/catch 里：任何异常只写日志，不向上抛，不会拖垮宿主回合。
-- 宿主门槛 `engines.dsh = ">=0.2.1-rc.1 <0.3.0"`：本插件用到的宿主 API 在 `0.2.1-rc.1` / `rc.2` / `rc.3` / `rc.4` / `rc.5` 里实现完全一致（rc.3 / rc.4 / rc.5 的 `dsh-system-prompt` / `dsh-agent` / `dsh-session` / `dsh-agent-loop` / `dsh-app-boot` 的 `lib/index.js` sha256 逐字节相同），所以门槛只设到 rc.1。**不要写成 `>=0.2.1`**——semver 里预发布版本不满足不含预发布标识的同段范围，`0.2.1-rc.3` 对 `>=0.2.1` 判为 `false`，会连 rc 版本一起挡掉。上界 `<0.3.0` 是安全阀：0.3.0 起若宿主 API 有变，插件应静默跳过而不是带着错误假设继续跑。门槛不满足时宿主会把整个 bundle 静默跳过（启动只留一行 `skipping profile bundle`）。
-- **升级宿主前请先看门槛**：`<0.3.0` 的上界意味着宿主升到 0.3.0 时本插件会**静默不加载**（`dsh-app-boot` 只往 stderr 写一行 `skipping profile bundle`）。请先看日志首行 `plugin activated: ... version=...`：没有这一行就是没加载。届时要么升级本插件并把上界往上放，要么临时把 `engines.dsh` 放宽（自担 API 漂移风险）。
+- 宿主门槛 `engines.dsh = ">=0.2.1-rc.1 <0.3.0-0"`：本插件用到的宿主 API 在 `0.2.1-rc.1` / `rc.2` / `rc.3` / `rc.4` / `rc.5` 里实现完全一致（rc.3 / rc.4 / rc.5 的 `dsh-system-prompt` / `dsh-agent` / `dsh-session` / `dsh-agent-loop` / `dsh-app-boot` 的 `lib/index.js` sha256 逐字节相同），所以门槛只设到 rc.1。**不要写成 `>=0.2.1`**——semver 里预发布版本不满足不含预发布标识的同段范围，`0.2.1-rc.3` 对 `>=0.2.1` 判为 `false`，会连 rc 版本一起挡掉。上界必须写成 `<0.3.0-0`：宿主用 `semver` 的 `includePrerelease: true` 判定门槛，写成 `<0.3.0` 时 `0.3.0-alpha.1` / `0.3.0-beta.2` 都会被判为满足（实测 `semver.satisfies('0.3.0-alpha.1', '>=0.2.1-rc.1 <0.3.0', {includePrerelease:true}) === true`），插件会带着未验证的假设加载到下一主线；`-0` 是显式的预发布截断。`scripts/check-metadata.mjs` 会强制检查这个写法。门槛不满足时宿主会把整个 bundle 静默跳过（启动只留一行 `skipping profile bundle`）。
+- **升级宿主前请先看门槛**：`<0.3.0-0` 的上界意味着宿主升到 0.3.0（含 `0.3.0-alpha*` / `0.3.0-beta*`）时本插件会**静默不加载**（`dsh-app-boot` 只往 stderr 写一行 `skipping profile bundle`）。请先看日志首行 `plugin activated: ... version=...`：没有这一行就是没加载。届时要么升级本插件并把上界往上放，要么临时把 `engines.dsh` 放宽（自担 API 漂移风险）。
 - `inject = ['systemPrompt']` 是 cordis 的**硬依赖**，不做「可选依赖」改造：本版本 `@deepseek-ai/cordis` 的 `Inject.resolve` 只接受「数组」或「name → config 映射」，没有 `required`/`optional` 语义；写成 `{ optional: [...] }` 会被当成「等一个叫 optional 的服务」，插件将永不激活。
 
 ## 已知限制
 
 - **补写消息以 `role: 'user'` 落盘**（`source.kind = 'plugin:turn-recovery'`）：宿主 session 层对 `source.kind` 不做枚举校验，插件侧也改不了 role。桌面前端按 `source.kind !== 'user'` 渲染成上下文卡片（不是用户气泡），mnemon 只收录 `source.kind === 'user'`，所以界面与记忆都不受污染；但**会话转录文件里它确实是一条 user 消息**，审计时要看 `source.kind` 区分。
 - **用户点停止的窗口**：宿主 `cancel()` 只清 inbox + abort，不 append 任何 session 事件。插件订阅了宿主 dispatch 的 `agent/inbox/discarded` 来撤掉自己那条补写，但该事件是否向插件广播取决于宿主的 dispatch 链路；收不到时，「用户已点停止、插件仍在 `delayMs` 后补写」这个窗口依然存在（默认 900ms，可通过 `delayMs` 调小）。真正发出去的那一回合仍受宿主 abort 语义约束。
-- **`sessionScope: 'root'` 的判定依据是 id 前缀 `session-`**：老版本（v3 日志）的纯 UUID 会话目录、`social-*` 社交桥会话都算「非根」，默认不处理。被过滤的会话每个 id 只记一条 `skip scope` 日志，不会静默消失。
+- **`sessionScope: 'root'` 的判定依据是宿主的 `Session.header`**：`origin === 'subagent'` 或 `delegationDepth > 0` 才算子代理会话，`orchestrator-*` 这类顶层会话会被正常处理（0.2.0 用 id 前缀判断，把它们全部判成子代理，实测日志里有 19 次静默跳过）。宿主没有 header 的场合（老宿主、测试桩）退回 id 形态：`session-*` / `orchestrator-*` 算根，纯 UUID / `social-*` 不算。被过滤的会话每个 id 只记一条 `skip scope` 日志，不会静默消失。
+- **可见字符是「按回合累计」而不是「末条消息」**：一个回合里先写了结论、后来又被工具调用打断的，累计口径下不算空（这是刻意的：用户此前已经看到了文字）。反过来，`aborted` / `interrupted` 等非 `completed` 回合一律不补写，即使它确实没留下正文 —— 那些回合多半是用户自己喊停的，再补一轮会变成「已取消还继续跑」。
 - **崩溃遗留**：补写已入队但宿主在认领前崩溃时，该消息可能在下次启动被重放。插件只认 id 匹配的认领（`NOT ours`），因此不会被这种消息骗成「补写回合」，但它仍可能作为一条插件消息出现在转录里。
 - **多宿主共用同一日志文件**：两个进程同时写同一路径时轮转可能失败，此时回退 `truncate(0)` 并记一条 `log rotate fell back to truncate`。
 - **生产环境尚未观测到真实补写**：截至 2026-10-30，本机生产日志里 `nudge DELIVERED` 仍为 0（空回合全部是 `aborted`），所有结论来自单测与 mock 复现。真机端到端（含「补写回合真的开起来」）仍是未验证项。

package/lib/index.js

@@ -11,10 +11,20 @@
  * 本插件做两件事：
  *   C) 监听 turn/end：若该回合所有助手消息的可见正文（剥离零宽字符后）为空，
  *      就通过 agent.send(msg, 'next-turn', true) 追加一条 plugin 消息，让模型
- *      在下一个回合把结论补出来。每回合最多 1 次，每会话每小时有上限，
+ *      在下一个回合把结论补出来。每回合最多 1 次，每会话每小时有上限（上限
+ *      落盘到 $DSH_HOME/state/turn-recovery/nudges.log，重启后仍然有效），
  *      补写回合再空则不再连环触发。
  *   A) 注册一段 system prompt（order 960）要求每回合都以可见正文收尾。
  *
+ * 0.2.1 适配性修复（针对宿主 0.2.2-alpha.3 实测）：
+ *   - 会话范围改按 SessionHeader 判定（origin/delegationDepth），不再靠 id 前缀；
+ *     orchestrator-* 这类顶层会话此前被判成子代理，19 次静默跳过。
+ *   - 取消策略由「后台黑名单 + 未知即前台」改为「前台白名单 + 未知即后台」：
+ *     宿主新增的 notice 形态来源不再误取消待发补写。
+ *   - prompt 段落注册失败改为 fail-closed（不再写 guard armed 谎报正常）。
+ *   - 投递前检查宿主 next-turn 队列，进程内标记丢失时不会重复投递。
+ *   - engines 上界收紧到 <0.3.0-0：<0.3.0 在 includePrerelease 下会放行 0.3.0-*。
+ *
  * 设计约束：
  *   1) 所有逻辑都包在 try/catch 里，任何异常只写日志，绝不向上抛，以免拖垮宿主回合。
  *   2) inject 是 cordis 的硬依赖（数组形式）。本版本 cordis 的 Inject.resolve
@@ -53,25 +63,20 @@ const SOURCE = Object.freeze({ kind: 'plugin:' + PLUGIN_ID, plugin: PLUGIN_ID, r
 const SOURCE_KIND = SOURCE.kind;
 
 /**
- * 宿主的「背景注入」来源，不算有人在说话（不取消待发补写）。
- * runtime-context 由 dsh-agent-loop 每步追加；time-context / skill-catalog /
- * dsh-mnemon / agent-instructions 是自动上下文；ptc-mode、model-selection、
- * session-reference、skill-invocation、compact-checkpoint 是宿主/插件写入的
- * 状态或上下文消息，都不会自己开新回合。宿主新增来源时宁可漏取消，也不要把
- * 真正的空回合补写误取消。任何以 `plugin:` 开头的来源也按背景处理。
+ * 前台来源：确实「有人在说话」的 user/message，只有它们会取消待发补写。
+ *
+ * 0.2.1 之前这里是**后台来源黑名单**（BACKGROUND_KINDS），没列到的来源一律按
+ * 真人插话处理。宿主后来新增的 form:"notice" 来源（dsh-tool-jobs、
+ * dsh-action-cards、dsh-plan-mode、dsh-tool-goal）以及 kind:"goal" /
+ * kind:"schedule" 的自动化回合都没在黑名单里，于是每一次都可能把排好的补写
+ * 取消掉——插件不报错、日志只写一行 CANCELLED，表现为「装了但没用」。
+ * 黑名单天生跟不上宿主的演进，改为白名单：**没见过的来源一律按后台处理**。
+ *
+ * 漏取消的代价很小：真人消息与自动化回合都会开新回合，turn/start 分支
+ * 本来就会丢弃上一回合的待发补写，这里只是提前一点点。
+ * 若某个自定义桥接需要取消语义，用配置 `foregroundKinds: ['wechat-bridge']` 补进来。
  */
-const BACKGROUND_KINDS = new Set([
-  'runtime-context',
-  'time-context',
-  'skill-catalog',
-  'dsh-mnemon',
-  'agent-instructions',
-  'ptc-mode',
-  'model-selection',
-  'session-reference',
-  'skill-invocation',
-  'compact-checkpoint',
-]);
+const DEFAULT_FOREGROUND_KINDS = Object.freeze(['user', 'agent-message']);
 const SECTION_NAME = 'turn-recovery';
 /** 950 已被 instruction-memory 占用；960 在其后、TOOL_BASH(1000) 之前。 */
 const SECTION_ORDER = 960;
@@ -200,10 +205,19 @@ export function apply(ctx, config) {
     // 0 表示关闭补写（而不是被 || 吞成 3）。
     maxNudgesPerHour: intOr(raw.maxNudgesPerHour, 3, 0, 1000),
     logFile: typeof raw.logFile === 'string' ? raw.logFile.trim() : '',
-    // 'root'（默认）只处理根会话（id 形如 session-<uuid>）；'all' 连子代理会话
-    // （裸 UUID）和社交桥会话（social-<hex> 等）一起处理。默认不碰子会话：
-    // 子代理「只调工具、不回正文」是正常收尾，补写会浪费 token 甚至改变委派行为。
+    // 'root'（默认）只处理根会话（header.delegationDepth 为 0 或缺省）；'all' 连
+    // 子代理会话一起处理。默认不碰子会话：子代理「只调工具、不回正文」是正常收尾，
+    // 补写会浪费 token 甚至改变委派行为。
     sessionScope: raw.sessionScope === 'all' ? 'all' : 'root',
+    // 追加的「前台来源」：默认只有 user / agent-message 会取消待发补写，
+    // 自定义桥接（如社交桥）需要取消语义时把自己的 source.kind 写进来。
+    foregroundKinds: (() => {
+      const list = Array.isArray(raw.foregroundKinds) ? raw.foregroundKinds : [];
+      const extra = list.filter((k) => typeof k === 'string' && k.trim() !== '').map((k) => k.trim());
+      return new Set([...DEFAULT_FOREGROUND_KINDS, ...extra]);
+    })(),
+    // 补写预算的持久化文件（跨重启限流）；默认 $DSH_HOME/state/turn-recovery/nudges.log。
+    budgetFile: typeof raw.budgetFile === 'string' ? raw.budgetFile.trim() : '',
   };
 
   // 日志位置优先跟随 DSH_HOME（多 profile / 自定义家目录时才不会写错地方）。
@@ -252,7 +266,10 @@ export function apply(ctx, config) {
   // 主日志写在 $DSH_HOME/logs；万一主路径不可写（受限环境/目录被锁），
   // 再退到系统临时目录，避免「插件其实活着但一行日志都没有」的误判。
   const log = (line) => {
-    const record = '[' + new Date().toISOString() + '] ' + line + '\n';
+    // 日志行内不允许出现换行：会话 id、错误文本都可能带 \n，拼进去就能在日志里
+    // 伪造出一行看似插件自己写的记录（伪造 turn/end 或 guard armed 会误导排障）。
+    const safe = String(line).replace(/[\r\n]+/g, ' ');
+    const record = '[' + new Date().toISOString() + '] ' + safe + '\n';
     maybeRotate();
     try {
       fs.mkdirSync(path.dirname(logPath), { recursive: true });
@@ -268,35 +285,141 @@ export function apply(ctx, config) {
     }
   };
 
+  /**
+   * 补写预算的跨进程持久化。
+   *
+   * nudgeTimes 挂在 WeakMap 的会话状态上，是纯内存态：宿主一重启就清零，
+   * 一个反复空回合的会话每次重启都能重新领满 maxNudgesPerHour 次补写。
+   * 重启不是罕见事件（升级、崩溃、切换模型），累起来就是白烧的 token，
+   * 所以把每次投递的时刻追加进一个小文件，进程启动后第一次见到某会话时
+   * 回读它最近一小时的记录。
+   *
+   * 约束：只用于限流，不参与任何判定；读写失败一律忽略（宁可多补一次，
+   * 也不能让限流文件的 IO 问题拖垮宿主回合）。多进程并发追加时可能丢几行，
+   * 这是可接受的——它只是预算，不是账本。
+   */
+  const budgetPath = cfg.budgetFile !== ''
+    ? cfg.budgetFile
+    : path.join(dshHome, 'state', 'turn-recovery', 'nudges.log');
+  const BUDGET_MAX_BYTES = 1024 * 1024;
+  let budgetHydrated = false;
+  /** session.id -> 最近一小时内的投递时刻（只在本进程内累计）。 */
+  const budgetHistory = new Map();
+
+  const hydrateBudget = () => {
+    if (budgetHydrated) return;
+    budgetHydrated = true;
+    try {
+      const rawText = fs.readFileSync(budgetPath, 'utf8');
+      const cutoff = Date.now() - HOUR_MS;
+      for (const line of rawText.split('\n')) {
+        const sp = line.indexOf(' ');
+        if (sp <= 0) continue;
+        const id = line.slice(0, sp);
+        const at = Number(line.slice(sp + 1).trim());
+        if (id === '' || !Number.isFinite(at) || at < cutoff) continue;
+        const list = budgetHistory.get(id);
+        if (list) list.push(at);
+        else budgetHistory.set(id, [at]);
+      }
+    } catch { /* 文件不存在或读不了：当作没有历史 */ }
+  };
+
+  /** 该会话最近一小时的投递时刻（合并持久化记录与本次进程内的记录）。 */
+  const historyOf = (session) => {
+    hydrateBudget();
+    const id = session && typeof session.id === 'string' ? session.id : '';
+    const persisted = id !== '' ? budgetHistory.get(id) : undefined;
+    return persisted ? persisted.slice() : [];
+  };
+
+  /** 记录一次真正投递成功的补写；文件过大时先按一小时窗口重写。 */
+  const recordNudge = (session, at) => {
+    const id = session && typeof session.id === 'string' ? session.id : '';
+    if (id === '') return;
+    try {
+      if (!budgetHistory.has(id)) budgetHistory.set(id, []);
+      budgetHistory.get(id).push(at);
+      fs.mkdirSync(path.dirname(budgetPath), { recursive: true });
+      let size = 0;
+      try { size = fs.statSync(budgetPath).size; } catch { /* 首次写入 */ }
+      if (size > BUDGET_MAX_BYTES) {
+        const cutoff = Date.now() - HOUR_MS;
+        const lines = [];
+        for (const [sid, times] of budgetHistory) {
+          for (const t of times) if (t >= cutoff) lines.push(sid + ' ' + t);
+        }
+        fs.writeFileSync(budgetPath, lines.join('\n') + (lines.length > 0 ? '\n' : ''));
+      } else {
+        fs.appendFileSync(budgetPath, id + ' ' + at + '\n');
+      }
+    } catch { /* 限流退化到内存态，不影响补写本身 */ }
+  };
+
   /**
    * 日志里的会话短标签。旧版直接 id.slice(0,8)，而根会话 id 形如
    * session-<uuid>，前 8 位恒为 "session-"，多会话根本分不开。
-   * 现在先剥掉 session- 前缀再取前 8 位；剥完为空则退回原 id 前 8 位。
+   * 现在先剥掉 session- / orchestrator- 前缀再取前 8 位；剥完为空则退回原 id 前 8 位。
    */
   const tag = (session) => {
     try {
       const id = session && typeof session.id === 'string' ? session.id : '';
       if (!id) return 'no-session';
-      const stripped = id.replace(/^session-/, '');
+      const stripped = id.replace(/^(session-|orchestrator-)/, '');
       return stripped ? stripped.slice(0, 8) : id.slice(0, 8);
     } catch { return 'no-session'; }
   };
 
   /**
-   * sessionScope='root' 时只认根会话；其余（子代理裸 UUID、social-<hex> 等）跳过。
+   * sessionScope='root' 时只认根会话；子代理会话一律跳过。
+   *
+   * 判据来自宿主的 SessionHeader（dsh-session 构造函数：
+   * `this.header = restoredHeader ?? snapshotSessionHeader(id, header)`）：
+   * 只有 `origin === 'subagent'` 或 `delegationDepth > 0` 才是子代理子会话，
+   * 顶层会话的 delegationDepth 为 0 或缺省。
+   *
+   * 0.2.0 用 /^session-/ 猜 id 形态，把所有 orchestrator-* 会话当成子代理
+   * 静默过滤掉（实测日志里有 19 条 skip scope: non-root session orchestrator）。
+   * 会话 id 的形态是宿主实现的细节，不该由插件推断。
+   *
+   * header 缺失（老宿主、鸭子类型对象、测试桩）时退回 id 形态判定：
+   * session-* / orchestrator-* 视为根会话，裸 UUID / social-* 跳过。
    * 过滤时给每个会话打一条日志（同一 id 只打一次）：否则「插件没加载」和
    * 「被 scope 静默过滤」在日志里长得一模一样，排障全靠猜。
    */
   const scopeSeen = new Set();
+
+  /** header 判定根会话；返回 null 表示无法判定（没有 header）。 */
+  const rootByHeader = (session) => {
+    let header;
+    try { header = session && session.header; } catch { return null; }
+    if (!header || typeof header !== 'object') return null;
+    if (header.origin === 'subagent') return false;
+    const depth = header.delegationDepth;
+    if (typeof depth === 'number' && Number.isFinite(depth) && depth > 0) return false;
+    return true;
+  };
+
+  /** 每个被过滤掉的会话只记一条日志（否则「没加载」和「被过滤」在日志里无法区分）。 */
+  const logScopeSkip = (session, why) => {
+    const id = session && typeof session.id === 'string' ? session.id : '';
+    if (id === '' || scopeSeen.has(id)) return;
+    if (scopeSeen.size < 200) scopeSeen.add(id);
+    log('skip scope: non-root session ' + id.slice(0, 12) + ' (sessionScope=root, ' + why + ')');
+  };
+
   const sessionInScope = (session) => {
     if (cfg.sessionScope === 'all') return true;
+    const byHeader = rootByHeader(session);
+    if (byHeader === true) return true;
+    if (byHeader === false) {
+      logScopeSkip(session, 'header says subagent');
+      return false;
+    }
     const id = session && typeof session.id === 'string' ? session.id : '';
-    if (/^session-/.test(id)) return true;
+    if (/^(session-|orchestrator-)/.test(id)) return true;
     if (id === '') return false;
-    if (!scopeSeen.has(id)) {
-      if (scopeSeen.size < 200) scopeSeen.add(id);
-      log('skip scope: non-root session ' + id.slice(0, 12) + ' (sessionScope=root)');
-    }
+    logScopeSkip(session, 'id is not a root shape and no header');
     return false;
   };
 
@@ -320,7 +443,14 @@ export function apply(ctx, config) {
       }
       log('prompt section registered: order=' + SECTION_ORDER + ' chars=' + text.length);
     } catch (err) {
+      // fail-closed：A 段装不上时不再启用补写，也不再写「guard armed」。
+      // 宿主对同名 section 重复注册是直接 throw（dsh-system-prompt 的 section
+      // 注册会拒绝重名），最常见的触发原因是同一插件被两个 bundle 各装了一次。
+      // 此时若照常 arm：两个实例各发一条补写；日志却写着「一切正常」，
+      // 而「222 字符的收尾指令其实没进 prompt」这个事实在日志里看不出来。
       log('prompt section registration FAILED: ' + errText(err));
+      log('guard NOT armed (fail-closed: prompt section registration failed)');
+      return;
     }
   }
 
@@ -364,7 +494,8 @@ export function apply(ctx, config) {
         nudgeDeliveredAt: 0,
         /** 定时器是为哪个回合排的；回合变了就该丢弃。 */
         pendingTurn: null,
-        nudgeTimes: [],
+        /** 本小时已投递的补写时刻：启动时用持久化记录补齐（跨重启限流）。 */
+        nudgeTimes: historyOf(session),
         timer: null,
       };
       state.set(session, s);
@@ -541,6 +672,22 @@ export function apply(ctx, config) {
     source: { ...SOURCE },
   });
 
+  /**
+   * 宿主的 next-turn 队列里是否已经躺着一笔本插件的补写。
+   *
+   * nudgeMessageId 是进程内记忆：宿主重启、插件热重载、同一插件被两个 bundle
+   * 各装一次时它都是空的，于是会对同一个空回合各投一笔，模型连着被唤醒两次。
+   * 队列本身是宿主维护的真相（agent.inbox.nextTurn），以它为准去重。
+   */
+  const pendingNudgeInInbox = (agent) => {
+    try {
+      const inbox = agent && agent.inbox;
+      const queue = inbox && Array.isArray(inbox.nextTurn) ? inbox.nextTurn : null;
+      if (!queue) return false;
+      return queue.some((m) => m && m.source && m.source.kind === SOURCE_KIND);
+    } catch { return false; }
+  };
+
   const deliver = (session, text) => {
     const agent = agentOf(session);
     if (!agent) {
@@ -614,6 +761,11 @@ export function apply(ctx, config) {
             return;
           }
           if (s.nudgeMessageId !== null) clearNudgeInFlight(s, 'claim timeout');
+          if (pendingNudgeInInbox(agentOf(session))) {
+            log('nudge SKIPPED: inbox already holds a pending turn-recovery nudge ['
+              + tag(session) + ']');
+            return;
+          }
           if (cfg.maxNudgesPerHour === 0) {
             log('nudge SKIPPED: maxNudgesPerHour=0 [' + tag(session) + ']');
             return;
@@ -630,6 +782,8 @@ export function apply(ctx, config) {
             s.nudgeMessageId = message.id;
             s.nudgeDeliveredAt = Date.now();
             s.nudgeTimes.push(Date.now());
+            // 跨重启限流：把投递时刻落盘，重启后的新进程回读最近一小时。
+            recordNudge(session, s.nudgeDeliveredAt);
             log('nudge awaiting claim id=' + String(message.id).slice(0, 8) + ' [' + tag(session) + ']');
           } else {
             clearNudgeInFlight(s, null);
@@ -686,13 +840,19 @@ export function apply(ctx, config) {
               + ' matched=true [' + tag(session) + ']');
             return;
           }
-          // 宿主的「背景注入」不是有人在说话：runtime-context 每步都追加一条
-          // （dsh-agent-loop），time-context/skill-catalog/dsh-mnemon/agent-instructions
-          // 等也是自动上下文；把它们当插话会让补写几乎必被取消（0.1.3 修过的老 bug）。
-          // 除此之外的一切来源——真人、子代理回报、微信/社交桥消息——都算「有动静」，
-          // 取消待发补写，避免补写插进别人的输入里。
-          const isBackground = BACKGROUND_KINDS.has(kind) || kind.startsWith('plugin:');
-          if (!isBackground) clearTimer(s, 'user message (' + (kind || 'no-kind') + ')');
+          // 只有「确实有人在说话」的来源才取消待发补写（见 DEFAULT_FOREGROUND_KINDS）：
+          // 真人输入与 agent-message 转交。其余一切——宿主的 runtime-context /
+          // time-context / skill-catalog / dsh-mnemon 等自动上下文、form:"notice"
+          // 的工具/卡片/计划/任务通知、kind:"goal"/"schedule" 的自动化回合，以及
+          // 未来新增的、本插件不认识的来源——都按后台处理，不取消。
+          // 0.2.0 用「后台黑名单 + 未知即前台」，宿主每加一个通知来源就可能让补写
+          // 被静默取消；白名单把默认值改成「不认识就当背景」，漏取消由 turn/start 兜底。
+          const form = source && typeof source.form === 'string' ? source.form : '';
+          // form:'notice' 是宿主的通知形态（tool-jobs / action-cards / plan-mode /
+          // tool-goal 都用它）：无论 kind 叫什么，它都不是人在说话。
+          if (form !== 'notice' && cfg.foregroundKinds.has(kind)) {
+            clearTimer(s, 'user message (' + kind + ')');
+          }
           return;
         }
 
@@ -782,7 +942,8 @@ export function apply(ctx, config) {
     });
   } catch { /* effect 不可用时忽略 */ }
 
-  log('guard armed (uptime=' + (Date.now() - startedAt) + 'ms)');
+  log('guard armed (instruction=' + (cfg.injectInstruction ? 'registered' : 'disabled')
+    + ', uptime=' + (Date.now() - startedAt) + 'ms)');
 }
 
 export default { name, inject, apply };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-turn-recovery",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "DSH plugin: detect assistant turns that end with no visible text (zero-width placeholder) and re-prompt the model to write the answer; also injects a visible-closing-answer system prompt rule.",
   "license": "MIT",
   "author": "HERO476",
@@ -38,7 +38,7 @@
   ],
   "engines": {
     "node": ">=20",
-    "dsh": ">=0.2.1-rc.1 <0.3.0"
+    "dsh": ">=0.2.1-rc.1 <0.3.0-0"
   },
   "scripts": {
     "test": "node test/guard.test.mjs",