dsh-turn-recovery 0.2.4 → 0.2.5

package/CHANGELOG.md

@@ -7,6 +7,59 @@
 > `@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.5] - 2026-11-12
+
+**宿主契约修正版**。三专家评审（架构 / 安全 / 验收）对着宿主 0.2.2-rc.1 的
+`app.asar` 源码与 8 天生产日志复核 0.2.4，查出一个「处理器在真实宿主上永远空转」
+的契约漂移、一条会把模型输出发给第三方的越权路径，以及若干状态文件与路径问题。
+
+### 修复（缺陷）
+
+- **`agent/inbox/discarded` 载荷漂移（P1）**：宿主 0.2.2-rc.1 只发
+  `{ message }`（`dsh-agent-loop/lib/index.js:199`，已从 asar 逐行核实），
+  而 0.2.4 读的是 `payload.agent` → 处理器永远在第一行 `return`：用户点「停止」
+  后待发补写不会被撤销，仍会多跑一个模型回合，且 `DISCARDED by host` 日志永不出现。
+  改为按 `message.id` 反查 `stateById` 中的在途补写，不再依赖载荷里的 agent/session。
+  单测夹具同步改成宿主真实形状（旧夹具自造 `{agent, message}`，所以 65 例全绿也测不到）。
+- **来源闸门（P1）**：新增 `nudgeSources`。`turn/end` 会检查本回合最后一条
+  `user/message` 的 `source.kind`，只有落在白名单（默认 = 前台白名单）才补写。
+  社交桥（`wechat-social-bridge` / `form: relay`）默认被排除：桥接器会把模型输出
+  发回给真人联系人，补写等于**替你对外发言**。
+- **伪造认领不得释放在途标记（P2）**：`clearNudgeInFlight` 原来在「id 不匹配即忽略」
+  之前无条件执行，同进程任一插件 append 一条同 kind、随意 id 的消息就能让守卫
+  多唤醒一次模型。现在只在真的对上 id 时清；过期由 120s 认领超时兜底。
+- **header 缺失时 fail-closed（P2）**：新增 `headerlessScope`，默认 `'out'`（不判定）。
+  旧版按 id 形态把 `session-*` 当根会话，可能给「无 header 的子代理」补写，
+  破坏委派语义。老宿主兼容可显式设 `'root'`。
+- **`sawTurnStart` 不再被误清（P2）**：`turn/start` 缺数值 `turn` 时，
+  后续 `assistant/message` 触发的重置会把 `sawTurnStart` 一并清成 false，
+  整个回合被判成「中途加载」而跳过判定。现在只补记 turn 号、保留 `sawTurnStart`。
+- **`logFile` / `budgetFile` 路径校验（P2）**：自定义路径必须 `.log` 结尾，否则回落默认并记
+  config issue；轮转前检查文件头是否为本插件日志（首字节 `[`），不是就拒绝 rename/truncate ——
+  避免一次配置手滑不可逆地毁掉无关文件。
+- **状态文件压缩（P2）**：`guard-ids.log` 此前只增不减，超 1 MiB 后读侧按字节截断会把
+  TTL 内的旧记录丢掉（晚到认领认不出 → 连环补写）。现在与预算文件同法按 TTL 原子压缩。
+  预算/guard 压缩时若文件里有内容却一条都解析不出来，判定为「不是我们的文件」并拒绝重写。
+
+### 加固
+
+- `stateById` 改为 LRU（命中刷新插入序），避免长跑 >500 会话时把活跃会话按插入序淘汰。
+- 日志压平扩展为 `\r \n U+2028 U+2029 ESC`（部分查看器把前两者当换行、把 ESC 当终端着色）。
+- 状态文件压缩、路径拒绝、来源拦截都会留一行日志，便于现场判定「为什么没补写」。
+
+### 测试
+
+- 65 → 76 例。新增：真实形状的丢弃事件（含陌生 id）、来源闸门（默认拦 / 显式放开）、
+  headerlessScope 两种取值、`sawTurnStart` 补记、guard-ids 压缩、`logFile` 回落、控制字符压平。
+- 测试夹具默认带根会话 header（0.2.5 起无 header 视为范围外），需要测无 header 时传 `__noHeader`。
+
+### 已知遗留
+
+- 「`agent/inbox/discarded` 是否真的广播到插件根 `ctx`」仍**未验证**；
+  收不到时 900ms 停止窗口依然存在（README 已如实标注）。
+- 补写投递 → 认领 → 跨重启去重整条链在真实宿主上仍**零生产证据**
+  （`delivered=0 claimed=0`），需按 README 的 dryRun 流程取证。
+
 ## [0.2.4] - 2026-11-09
 
 **运行期复核版**。0.2.3 之后按 8 天生产日志（645 个 `turn/end`）回头复查代码，

package/README.md

@@ -64,8 +64,12 @@
     maxNudgesPerHour: 3      # 每会话每小时的补写上限（0 = 关闭补写）
     sessionScope: root       # root = 只处理根会话（按 SessionHeader 判定）；all = 连子代理会话一起
     foregroundKinds: []      # 追加「会取消待发补写」的来源 kind（默认 user / agent-message）
+    nudgeSources: []         # 允许被补写的「回合发起来源」；空 = 沿用 foregroundKinds
+                             # 社交桥（wechat-social-bridge 等）默认**不在**其中：模型输出
+                             # 可能被转发给第三方联系人，补写等于替你对外发言
+    headerlessScope: out     # 会话无 SessionHeader 时的判定：out = 不碰（默认）；root = 沿用旧版 id 形态猜
     budgetFile: ''           # 空 = <DSH_HOME>/state/turn-recovery/nudges.log（跨重启限流）
-                             # 同目录还会写 guard-ids.log（跨重启认出晚到认领的补写 id）
+                             # 必须 .log 结尾；同目录还会写 guard-ids.log（跨重启认出晚到认领的补写 id）
     logFile: ''              # 空 = <DSH_HOME>/logs/turn-recovery.log
     logTurns: empty          # empty = 只记空回合/被跳过判定的回合；all = 连正常回合也记
     dryRun: false            # true = 判定/限流/日志全部照走，但不真的投递（验证用）
@@ -121,7 +125,7 @@
 
 `version=` 是进程里真正加载的版本号（从包自身 `package.json` 读）——**升级后先看这一行**，不要靠「某个日志字段有没有」推断跑的是哪一版（0.1.4 与 0.1.5 都打过 `sawStart`，这个推断会错）。
 
-排查常用短语：`config issue`（配置写错，插件仍启用）、`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 对不上，已忽略）、`LATE, from guardIds`（认领超时后才到，仍按补写回合处理）、`DISCARDED by host`（用户停止，补写被丢弃）、`a nudge is already awaiting claim`（上一笔还没被认领）、`skipped:in-flight`（本回合没排上，因为上一笔仍在途 —— 不算「已补过」）、`turn N already handled`（该回合确实排过或确实被限流）、`DROPPED: turn moved on`（定时器到点时会话已进入下一回合）、`stop chaining`（补写回合又空，按设计不再连环）、`budget exhausted`（本小时额度用完）。
+排查常用短语：`config issue`（配置写错，插件仍启用）、`skip scope`（被 `sessionScope` 过滤掉的会话，括号里写明是 `header says subagent` 还是 `no header (headerlessScope=out)`）、`scope fallback`（`headerlessScope: 'root'` 时靠 id 形态放行的会话，首次记一行）、`guard NOT armed (fail-closed`（同名 prompt 段落已被占用，插件整体不启用，不再谎报 armed）、`inbox already holds a pending turn-recovery nudge`（队列里已有一笔，未重复投递）、`turn/start not observed`（热加载中途，不判定）、`NOT ours`（同来源但 id 对不上，已忽略；0.2.5 起不再因此清在途标记）、`LATE, from guardIds`（认领超时后才到，仍按补写回合处理）、`DISCARDED by host`（用户停止，补写被丢弃）、`is not an in-flight nudge`（丢弃事件里的 id 不是我们的在途补写）、`origin=… not in nudge sources`（来源闸门拦下的空回合，例如社交桥）、`a nudge is already awaiting claim`（上一笔还没被认领）、`skipped:in-flight`（本回合没排上，因为上一笔仍在途 —— 不算「已补过」）、`turn N already handled`（该回合确实排过或确实被限流）、`DROPPED: turn moved on`（定时器到点时会话已进入下一回合）、`stop chaining`（补写回合又空，按设计不再连环）、`budget exhausted`（本小时额度用完）、`guard ids compacted` / `budget compact skipped`（状态文件压缩结果）、`log rotate skipped: file does not look like`（`logFile` 配到了别的文件，拒绝轮转它）。
 
 ## 实现约束
 
@@ -139,11 +143,12 @@
 ## 已知限制
 
 - **会话状态是双索引**：`state` 是 WeakMap（按 session 对象身份，快路径），另有有界（500 条）的 `stateById`（按 `session.id`，兜底）。宿主在某些代码路径上会给出不同的 session 实例；只按对象身份索引时，`turn/start` 与 `turn/end` 会落在两份状态上，`sawTurnStart` 恒为 false、判定链整体静默早退（只留一行 `turn/start not observed`）。现在两个索引同时写，`agent/disposed` 时同时清。
+- **补写只在「人类发起」的回合里发生（0.2.5 来源闸门）**：`turn/end` 会检查本回合最后一条 `user/message` 的 `source.kind`，只有落在 `nudgeSources`（默认等于前台白名单 `user` / `agent-message`）里才补写。原因是社交桥（`source.kind='wechat-social-bridge'`, `form='relay'`）这类会话里，桥接器会把模型输出发回给真实的微信/QQ 联系人 —— 插件往这种会话塞一句"请直接输出纯文本"，等于**替你对外发言**。需要给桥接对话也保留保护时，把该 kind 写进 `nudgeSources` 显式开启。本回合没有 `user/message`（拿不到来源）时按"无法判定"放行，日志里能看到判定过程。
 - **补写消息以 `role: 'user'` 落盘**（`source.kind = 'plugin:turn-recovery'`）：宿主 session 层对 `source.kind` 不做枚举校验（只要求非空字符串），插件侧也改不了 role。桌面前端按 `source.kind !== 'user'` 渲染成上下文卡片（不是用户气泡），mnemon 只收录 `source.kind === 'user'`，所以界面与记忆都不受污染；但**会话转录文件里它确实是一条 user 消息**，审计时要看 `source.kind` 区分。另外 `plugin:*` 这个前缀不在宿主 `MessageSourceMap` 的类型联合里 —— 运行时不受影响（前端对未知 kind 走 `default` 分支，显示为「请求」卡片），但下游按类型联合写的消费者会漏掉它。
-- **用户点停止的窗口**：宿主 `cancel()` 只清 inbox + abort，不 append 任何 session 事件。插件订阅了宿主 dispatch 的 `agent/inbox/discarded` 来撤掉自己那条补写，但该事件是否向插件广播取决于宿主的 dispatch 链路；收不到时，「用户已点停止、插件仍在 `delayMs` 后补写」这个窗口依然存在（默认 900ms，可通过 `delayMs` 调小）。真正发出去的那一回合仍受宿主 abort 语义约束。
-- **`sessionScope: 'root'` 的判定依据是宿主的 `Session.header`**：`origin === 'subagent'` 或 `delegationDepth > 0` 才算子代理会话，`orchestrator-*` 这类顶层会话会被正常处理（0.2.0 用 id 前缀判断，把它们全部判成子代理，实测日志里有 19 次静默跳过）。宿主没有 header 的场合（老宿主、测试桩）退回 id 形态：`session-*` / `orchestrator-*` 算根，纯 UUID / `social-*` 不算。被过滤的会话每个 id 只记一条 `skip scope` 日志，不会静默消失。
+- **用户点停止的窗口**：宿主 `cancel()` 只清 inbox + abort，不 append 任何 session 事件。插件订阅宿主的 `agent/inbox/discarded` 来撤掉自己那条补写。0.2.4 及更早读的是 `payload.agent`，而宿主 0.2.2-rc.1 实际只发 `{ message }`（`dsh-agent-loop/lib/index.js:199`），于是处理器永远在第一行 return —— 0.2.5 改为按 `message.id` 反查在途补写，真实形状下才会真的撤掉定时器。**仍未验证**的是：该事件是否向插件的根 `ctx` 广播（宿主在自己的 `ownerCtx` 上监听 `agent/disposed`，说明 agent 作用域事件存在）。收不到时，「用户已点停止、插件仍在 `delayMs` 后补写」这个窗口依然存在（默认 900ms，可通过 `delayMs` 调小）。真正发出去的那一回合仍受宿主 abort 语义约束。
+- **`sessionScope: 'root'` 的判定依据是宿主的 `Session.header`**：`origin === 'subagent'` 或 `delegationDepth > 0` 才算子代理会话，`orchestrator-*` 这类顶层会话会被正常处理（0.2.0 用 id 前缀判断，把它们全部判成子代理，实测日志里有 19 次静默跳过）。**0.2.5 起**：拿不到 header 时默认**不判定**（`headerlessScope: 'out'`，fail-closed）—— 旧版按 id 形态把 `session-*` / `orchestrator-*` 当根会话，于是「无 header 的子代理」也会被补写，往子代理里塞"不要调用工具"会破坏委派语义。确有老宿主需要兼容时显式设 `headerlessScope: 'root'`（首次放行会记一行 `scope fallback`）。被过滤的会话每个 id 只记一条 `skip scope` 日志，不会静默消失。
 - **可见字符是「按回合累计」而不是「末条消息」**：一个回合里先写了结论、后来又被工具调用打断的，累计口径下不算空（这是刻意的：用户此前已经看到了文字）。反过来，`aborted` / `interrupted` 等非 `completed` 回合一律不补写，即使它确实没留下正文 —— 那些回合多半是用户自己喊停的，再补一轮会变成「已取消还继续跑」。
-- **崩溃遗留**：补写已入队但宿主在认领前崩溃时，该消息可能在下次启动被重放。插件只认 id 匹配的认领（`NOT ours`），因此不会被这种消息骗成「补写回合」，但它仍可能作为一条插件消息出现在转录里。为覆盖「120s 认领超时后才被认领」与「重启后才被认领」两种情形，最近 8 条投递 id 会同时留在内存与 `<budgetFile 同目录>/guard-ids.log` 里（`LATE, from guardIds`），重启后仍能认出它们，不会把补写回合再当成真空回合补第二笔。
+- **崩溃遗留**：补写已入队但宿主在认领前崩溃时，该消息可能在下次启动被重放。插件只认 id 匹配的认领（`NOT ours`），因此不会被这种消息骗成「补写回合」，但它仍可能作为一条插件消息出现在转录里。为覆盖「120s 认领超时后才被认领」与「重启后才被认领」两种情形，最近 8 条投递 id 会同时留在内存与 `<budgetFile 同目录>/guard-ids.log` 里（`LATE, from guardIds`），重启后仍能认出它们，不会把补写回合再当成真空回合补第二笔。**0.2.5 起**该文件超过 1 MiB 会按 TTL 原子压缩（`guard ids compacted: lines=N`）—— 旧版只增不减，而且读侧按字节截断会把 TTL 内的旧记录丢掉，反而让「晚到认领」认不出。
 - **预算文件是不可信输入**：解析时会丢弃「晚于当前时钟 +5 分钟」的时间戳（否则 `now - t` 为负、该会话被永久判成预算耗尽），并且整份文件只在 1 MiB 以内整读、超过就只读尾部（避免配置写错指向几百 MB 的文件时同步阻塞宿主）。写入用 JSON 行（会话 id 含空格也不会被截断），压缩是「重读磁盘 + 临时文件原子替换」，不会覆盖另一个进程刚追加的行。
 - **多进程（桌面宿主 + 独立的 web/headless 宿主）**：各自一套内存态，`agent.inbox.nextTurn` 只对本进程可见。预算文件与补写 id 文件是共享的，因此限流大致成立，但「同一会话同时被两个宿主打开」仍可能各补一笔。同一会话请只用一个宿主。
 - **`dryRun` 不写预算文件**：判定链、日志、限流检查照走，但不投递、不记账，所以它只能证明「判定会发生」，不能用来验证限流是否生效（日志里的 `budgetUsed=n/max` 是当时的已用额度）。

package/lib/index.js

@@ -191,7 +191,7 @@ function enabledOr(value, fallback) {
 const CONFIG_KEYS = new Set([
   'enabled', 'injectInstruction', 'dryRun', 'instructionText',
   'minVisibleChars', 'delayMs', 'maxNudgesPerHour', 'logFile', 'logTurns',
-  'sessionScope', 'foregroundKinds', 'budgetFile',
+  'sessionScope', 'foregroundKinds', 'nudgeSources', 'headerlessScope', 'budgetFile',
 ]);
 const NUMERIC_KEYS = ['minVisibleChars', 'delayMs', 'maxNudgesPerHour'];
 const STRING_KEYS = ['instructionText', 'logFile', 'budgetFile'];
@@ -260,6 +260,15 @@ function describeConfigIssues(raw) {
     const bad = raw.foregroundKinds.filter((k) => typeof k !== 'string' || k.trim() === '').length;
     if (bad > 0) issues.push(bad + ' non-string/empty entry in "foregroundKinds" -> dropped');
   }
+  if (raw.nudgeSources !== undefined && !Array.isArray(raw.nudgeSources)) {
+    issues.push('"nudgeSources" expects an array, got ' + brief(raw.nudgeSources) + ' -> ignored');
+  } else if (Array.isArray(raw.nudgeSources)) {
+    const bad = raw.nudgeSources.filter((k) => typeof k !== 'string' || k.trim() === '').length;
+    if (bad > 0) issues.push(bad + ' non-string/empty entry in "nudgeSources" -> dropped');
+  }
+  if (raw.headerlessScope !== undefined && raw.headerlessScope !== 'out' && raw.headerlessScope !== 'root') {
+    issues.push('"headerlessScope" expects "out" | "root", got ' + brief(raw.headerlessScope) + ' -> "out"');
+  }
   if (raw.logTurns !== undefined && raw.logTurns !== 'empty' && raw.logTurns !== 'all') {
     issues.push('"logTurns" expects "empty" | "all", got ' + brief(raw.logTurns) + ' -> "empty"');
   }
@@ -332,6 +341,31 @@ export function apply(ctx, config) {
       const extra = list.filter((k) => typeof k === 'string' && k.trim() !== '').map((k) => k.trim());
       return new Set([...DEFAULT_FOREGROUND_KINDS, ...extra]);
     })(),
+    /**
+     * 允许被补写的「回合发起来源」（0.2.5）。
+     *
+     * 决定的是「这个会话里该不该由插件插一句话」，与 foregroundKinds 的
+     * 「谁的消息能取消待发补写」是两件事：
+     *   - 社交桥（source.kind='wechat-social-bridge', form='relay'）把真人微信
+     *     消息送进会话，桥接器又会把模型输出发回给联系人。它不在前台白名单里，
+     *     于是 0.2.4 既不会被它取消补写、也不会因此排除该会话 —— 一旦那里出现
+     *     completed 空回合，插件就会往一段真人对话里塞"请直接输出纯文本"，
+     *     模型输出经桥接成为对外发文。这是未授权的外部副作用，必须默认关掉。
+     *   - 显式列在这个白名单里的来源才允许补写；空数组 = 沿用 foregroundKinds。
+     * 想给桥接对话也保留保护的用户，把 kind 显式写进来即可（自担对外发言的语义）。
+     */
+    nudgeSources: (() => {
+      const list = Array.isArray(raw.nudgeSources) ? raw.nudgeSources : [];
+      const extra = list.filter((k) => typeof k === 'string' && k.trim() !== '').map((k) => k.trim());
+      return extra.length > 0 ? new Set(extra) : null;
+    })(),
+    /**
+     * 会话 header 缺失时怎么判定（0.2.5）。宿主的 SessionHeader 是根/子代理的
+     * 唯一可信判据；拿不到时旧版按 id 形态猜（session-* 当根会话），于是
+     * 「无 header 且 id 形如 session-* 的子代理」会被补写，破坏委派语义。
+     * 默认 'out'：无法判定就不碰；确有老宿主需要时显式设成 'root'。
+     */
+    headerlessScope: raw.headerlessScope === 'root' ? 'root' : 'out',
     // 补写预算的持久化文件（跨重启限流）；默认 $DSH_HOME/state/turn-recovery/nudges.log。
     budgetFile: typeof raw.budgetFile === 'string' ? raw.budgetFile.trim() : '',
     // 干跑：判定、限流、日志全部照常走，唯独不真的把补写投进队列。
@@ -348,7 +382,12 @@ export function apply(ctx, config) {
   const dshHome = typeof process.env.DSH_HOME === 'string' && process.env.DSH_HOME.trim() !== ''
     ? process.env.DSH_HOME.trim()
     : path.join(os.homedir(), '.dsh');
-  const logPath = cfg.logFile !== '' ? cfg.logFile : path.join(dshHome, 'logs', 'turn-recovery.log');
+  // 0.2.5：自定义路径必须像日志文件（.log 结尾）。否则一次配置手滑就可能让
+  // 轮转/压缩逻辑去 rename 或 truncate 一个无关文件 —— 那是不可逆的破坏。
+  const customLogRejected = cfg.logFile !== '' && !/\.log$/i.test(cfg.logFile);
+  const logPath = (cfg.logFile !== '' && !customLogRejected)
+    ? cfg.logFile
+    : path.join(dshHome, 'logs', 'turn-recovery.log');
   const fallbackLogPath = path.join(os.tmpdir(), 'turn-recovery.log');
   const startedAt = Date.now();
   let lastRotateCheck = 0;
@@ -359,9 +398,33 @@ export function apply(ctx, config) {
    * 先试 rename，失败就退回 truncate(0) —— 宁可丢历史，也不能让日志无限长。
    */
   let rotateWarned = false;
+  let foreignLogWarned = false;
+  /**
+   * 文件头是否像本插件写的日志（首字节 '['，即 ISO 时间戳的开头）。
+   * 轮转/截断前必须过这一关：`logFile` 配错时，旧版会直接 rename 或 truncate
+   * 用户的任意文件；现在宁可让日志继续长，也不动一个不认识的文件。
+   */
+  const looksLikeOurLog = (file) => {
+    try {
+      const fd = fs.openSync(file, 'r');
+      try {
+        const buf = Buffer.alloc(1);
+        const read = fs.readSync(fd, buf, 0, 1, 0);
+        if (read === 0) return true; // 空文件：轮转/截断都无害
+        return buf[0] === 0x5B; // '['
+      } finally { fs.closeSync(fd); }
+    } catch { return false; }
+  };
   const rotateIfNeeded = (file) => {
     try {
       if (fs.statSync(file).size <= LOG_MAX_BYTES) return;
+      if (!looksLikeOurLog(file)) {
+        if (!foreignLogWarned) {
+          foreignLogWarned = true;
+          log('log rotate skipped: file does not look like a turn-recovery log (' + file + ')');
+        }
+        return;
+      }
       const backup = file + '.1';
       try {
         if (fs.existsSync(backup)) fs.unlinkSync(backup);
@@ -397,7 +460,9 @@ export function apply(ctx, config) {
   const log = (line) => {
     // 日志行内不允许出现换行：会话 id、错误文本都可能带 \n，拼进去就能在日志里
     // 伪造出一行看似插件自己写的记录（伪造 turn/end 或 guard armed 会误导排障）。
-    const safe = String(line).replace(/[\r\n]+/g, ' ');
+    // 0.2.5 起连 U+2028/U+2029（部分查看器当换行）与 ESC（终端着色）一起压平：
+    // 会话 id 由宿主/桥接插件产生，现网已出现 social-*、bili-whale 这类非 UUID 形态。
+    const safe = String(line).replace(/[\r\n\u2028\u2029\x1b]+/g, ' ');
     const record = '[' + new Date().toISOString() + '] ' + safe + '\n';
     maybeRotate();
     try {
@@ -431,9 +496,12 @@ export function apply(ctx, config) {
    * 也不能让限流文件的 IO 问题拖垮宿主回合）。多进程并发追加时可能丢几行，
    * 这是可接受的——它只是预算，不是账本。
    */
-  const budgetPath = cfg.budgetFile !== ''
+  const customBudgetRejected = cfg.budgetFile !== '' && !/\.log$/i.test(cfg.budgetFile);
+  const budgetPath = (cfg.budgetFile !== '' && !customBudgetRejected)
     ? cfg.budgetFile
     : path.join(dshHome, 'state', 'turn-recovery', 'nudges.log');
+  if (customLogRejected) configIssues.push('"logFile" must end with .log -> default used');
+  if (customBudgetRejected) configIssues.push('"budgetFile" must end with .log -> default used');
   const BUDGET_MAX_BYTES = 1024 * 1024;
   /** 已投递补写 id 的持久化文件（跨重启识别晚到认领用），与预算文件同目录。 */
   const guardPath = path.join(path.dirname(budgetPath), 'guard-ids.log');
@@ -548,6 +616,64 @@ export function apply(ctx, config) {
     return list.slice(-GUARD_IDS_MAX);
   };
 
+  /**
+   * guard-ids 文件压缩（0.2.5）。这个文件此前是唯一「只增不减」的持久文件：
+   * 每投递一笔写一行，永不轮转；读侧只取尾部 1 MiB，于是超过 1 MiB 后 TTL 内
+   * 的旧记录会被按字节截断丢掉 —— 重启后的晚到认领认不出，反而触发连环补写
+   * （正是这个文件想解决的场景）。现在与预算文件同法：重读磁盘 → 只留 TTL 内
+   * 且每会话至多 GUARD_IDS_MAX 条 → 原子替换。
+   * 若文件内容一条都解析不出来（被别的程序写成了别的东西），拒绝重写。
+   */
+  let guardCompactWarned = false;
+  const compactGuardIds = (now) => {
+    try {
+      const rawText = readTail(guardPath, BUDGET_MAX_BYTES);
+      const floor = now - GUARD_ID_TTL_MS;
+      const keep = new Map(); // sid -> [{ id, at }]
+      let parsed = 0;
+      for (const line of rawText.split('\n')) {
+        const text = line.trim();
+        if (text === '') continue;
+        let rec;
+        try { rec = JSON.parse(text); } catch { continue; }
+        if (!rec || typeof rec.id !== 'string' || typeof rec.sid !== 'string') continue;
+        const at = Number(rec.at);
+        if (!Number.isFinite(at) || at < floor || at > now + BUDGET_FUTURE_SKEW_MS) continue;
+        parsed += 1;
+        const list = keep.get(rec.sid) || [];
+        const seen = list.find((x) => x.id === rec.id);
+        if (seen) seen.at = Math.max(seen.at, at);
+        else list.push({ id: rec.id, at });
+        keep.set(rec.sid, list);
+      }
+      if (parsed === 0 && rawText.trim() !== '') {
+        if (!guardCompactWarned) {
+          guardCompactWarned = true;
+          log('guard ids compact skipped: file does not look like turn-recovery state ('
+            + guardPath + ')');
+        }
+        return;
+      }
+      const lines = [];
+      for (const [sid, entries] of keep) {
+        for (const entry of entries.slice(-GUARD_IDS_MAX)) {
+          lines.push(JSON.stringify({ sid, id: entry.id, at: entry.at }));
+        }
+      }
+      const tmp = guardPath + '.tmp-' + process.pid;
+      fs.writeFileSync(tmp, lines.length > 0 ? lines.join('\n') + '\n' : '');
+      try {
+        fs.renameSync(tmp, guardPath);
+      } catch (err) {
+        try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+        throw err;
+      }
+      log('guard ids compacted: lines=' + lines.length);
+    } catch (err) {
+      log('guard ids compact FAILED: ' + errText(err));
+    }
+  };
+
   const recordGuardId = (session, id, at) => {
     const sid = session && typeof session.id === 'string' ? session.id : '';
     if (sid === '' || typeof id !== 'string' || id === '') return;
@@ -558,6 +684,9 @@ export function apply(ctx, config) {
       while (list.length > GUARD_IDS_MAX) list.shift();
       fs.mkdirSync(path.dirname(guardPath), { recursive: true });
       fs.appendFileSync(guardPath, JSON.stringify({ sid, id, at }) + '\n');
+      let size = 0;
+      try { size = fs.statSync(guardPath).size; } catch { /* 首次写入 */ }
+      if (size > BUDGET_MAX_BYTES) compactGuardIds(Date.now());
     } catch { /* 只服务于去重，写失败不影响补写本身 */ }
   };
 
@@ -590,17 +719,31 @@ export function apply(ctx, config) {
    * 旧版直接用内存 map 覆盖写整份文件 —— 多进程（桌面宿主 + 独立 web/headless）
    * 同时运行时，会把对方刚追加的行整段抹掉，预算就少算、于是多补。
    */
+  let budgetCompactWarned = false;
   const compactBudget = (now) => {
+    let parsed = 0;
+    let rawText = '';
     try {
-      const rawText = readTail(budgetPath, BUDGET_MAX_BYTES);
+      rawText = readTail(budgetPath, BUDGET_MAX_BYTES);
       for (const line of rawText.split('\n')) {
         const rec = parseBudgetLine(line, now);
         if (!rec) continue;
+        parsed += 1;
         const list = budgetHistory.get(rec.id);
         if (!list) budgetHistory.set(rec.id, [rec.at]);
         else if (list.indexOf(rec.at) < 0) list.push(rec.at);
       }
     } catch { /* 读不到就只用内存态 */ }
+    // 文件里有内容却一条都解析不出来：这不是我们的预算文件（配置指错了，或被
+    // 别的程序写成了别的东西）。重写它会毁掉别人的数据，宁可不压缩、只留一行。
+    if (parsed === 0 && rawText.trim() !== '') {
+      if (!budgetCompactWarned) {
+        budgetCompactWarned = true;
+        log('budget compact skipped: file does not look like turn-recovery state ('
+          + budgetPath + ')');
+      }
+      return;
+    }
     pruneBudgetHistory(now);
     const lines = [];
     for (const [sid, times] of budgetHistory) {
@@ -639,14 +782,18 @@ export function apply(ctx, config) {
    * 日志里的会话短标签。旧版直接 id.slice(0,8)，而根会话 id 形如
    * session-<uuid>，前 8 位恒为 "session-"，多会话根本分不开。
    * 现在先剥掉 session- / orchestrator- / worker- 前缀再取前 8 位；剥完为空则退回原 id 前 8 位。
+   * 只拿到 id（没有 session 对象）的路径——例如宿主只发 { message } 的
+   * agent/inbox/discarded——直接复用 shortId。
    */
+  const shortId = (rawId) => {
+    const id = typeof rawId === 'string' ? rawId : '';
+    if (id === '') return 'no-session';
+    const stripped = id.replace(/^(session-|orchestrator-|worker-)/, '');
+    return stripped ? stripped.slice(0, 8) : id.slice(0, 8);
+  };
+
   const tag = (session) => {
-    try {
-      const id = session && typeof session.id === 'string' ? session.id : '';
-      if (!id) return 'no-session';
-      const stripped = id.replace(/^(session-|orchestrator-|worker-)/, '');
-      return stripped ? stripped.slice(0, 8) : id.slice(0, 8);
-    } catch { return 'no-session'; }
+    try { return shortId(session && session.id); } catch { return 'no-session'; }
   };
 
   /**
@@ -668,6 +815,8 @@ export function apply(ctx, config) {
    */
   const scopeSeen = new Set();
   let scopeSeenCapped = false;
+  /** headerlessScope='root' 时，每个「靠 id 形态放行」的会话只记一条日志。 */
+  const headerlessSeen = new Set();
 
   /** header 判定根会话；返回 null 表示无法判定（没有 header）。 */
   const rootByHeader = (session) => {
@@ -702,9 +851,19 @@ export function apply(ctx, config) {
       return false;
     }
     const id = session && typeof session.id === 'string' ? session.id : '';
-    if (/^(session-|orchestrator-)/.test(id)) return true;
-    if (id === '') return false;
-    logScopeSkip(session, 'id is not a root shape and no header');
+    // 0.2.5：拿不到 header 时默认**不碰**（fail-closed）。旧版按 id 形态把
+    // session-* / orchestrator-* 当根会话，于是一个「无 header 且 id 形如
+    // session-*」的子代理会话也会被补写 —— 往子代理里塞"不要调用工具"会破坏
+    // 委派语义。确有老宿主需要兼容时，显式设 headerlessScope: 'root'。
+    if (cfg.headerlessScope === 'root' && /^(session-|orchestrator-)/.test(id)) {
+      if (!headerlessSeen.has(id) && headerlessSeen.size < SCOPE_SEEN_MAX) {
+        headerlessSeen.add(id);
+        log('scope fallback: no header, id shape=root -> in scope (headerlessScope=root) ['
+          + shortId(id) + ']');
+      }
+      return true;
+    }
+    logScopeSkip(session, id === '' ? 'no header and no id' : 'no header (headerlessScope=out)');
     return false;
   };
 
@@ -815,6 +974,12 @@ export function apply(ctx, config) {
          * 拿去补写会对着「本来有正文的回合」发假提醒。
          */
         sawTurnStart: false,
+        /**
+         * 本回合最近一条非补写 user/message 的来源 kind（'' = 本回合没见到）。
+         * 0.2.5 的来源闸门用它：只有来源在 nudgeSources（默认前台白名单）里
+         * 才允许补写，避免往社交桥这类「模型输出会被转发给第三方」的会话里插话。
+         */
+        turnOrigin: '',
         /**
          * 本回合已经「处理过」：要么排上了补写，要么在排补写前就被限流/去重挡下。
          * 只在 turn/end 的判定走完之后置位 —— 旧版在调用 scheduleNudge 之前就置位，
@@ -854,15 +1019,21 @@ export function apply(ctx, config) {
     // 两个索引都写：对象身份是最快路径，id 是宿主换 session 实例时的兜底。
     if (session && typeof session === 'object') state.set(session, s);
     const sid = session && typeof session.id === 'string' ? session.id : '';
-    if (sid !== '' && stateById.get(sid) !== s) {
-      if (stateById.size >= STATE_BY_ID_MAX && !stateById.has(sid)) {
-        // Map 保序，第一个就是最早插入的一条。淘汰是安全的：该会话的下一次
-        // 事件会拿到一个新状态（字段齐全，只是当回合累计值从零开始），
-        // 而状态本身是缓存，淘汰不等同于丢判定能力。
-        const oldest = stateById.keys().next();
-        if (!oldest.done) stateById.delete(oldest.value);
+    if (sid !== '') {
+      const existing = stateById.get(sid);
+      if (existing === s) {
+        // LRU：命中即刷新插入顺序（Map 保序）。旧版按纯插入序淘汰，长跑 >500 个
+        // 会话时会把仍在活跃的会话踢掉，它的 sawTurnStart 随即复位 → 静默漏补。
+        stateById.delete(sid);
+        stateById.set(sid, s);
+      } else {
+        if (stateById.size >= STATE_BY_ID_MAX && !stateById.has(sid)) {
+          // Map 保序，第一个就是最久未使用的（见上面的命中刷新）。
+          const oldest = stateById.keys().next();
+          if (!oldest.done) stateById.delete(oldest.value);
+        }
+        stateById.set(sid, s);
       }
-      stateById.set(sid, s);
     }
     return s;
   };
@@ -1003,26 +1174,33 @@ export function apply(ctx, config) {
   }
 
   /**
-   * P2-C 缓解：用户点「停止」时宿主 cancel() 只清 inbox + abort，不 append 任何
-   * session 事件，插件单靠 session/event 无从得知那条补写已被丢弃，900ms 后照发，
-   * 于是「用户已经喊停」还会多跑一轮模型。
-   * 宿主（rc.5 bundle 内确认存在）会 dispatch 'agent/inbox/discarded'。这里尽力订阅，
-   * 但只在「被丢弃消息的 id 恰好是我们的补写」时才撤定时器：id 不匹配、或宿主根本
-   * 不向插件广播该事件时，行为退回旧版（不会误伤别的消息、也不会乱取消）。
+   * P2-C 缓解（0.2.5 修）：用户点「停止」时宿主 cancel() 只清 inbox + abort，
+   * 不 append 任何 session 事件，插件单靠 session/event 无从得知那条补写已被丢弃，
+   * delayMs 后照发，于是「用户已经喊停」还会多跑一轮模型。
+   *
+   * 宿主 0.2.2-rc.1 的真实载荷（app.asar 内 dsh-agent-loop/lib/index.js:199）：
+   *   this.dispatch.emit("agent/inbox/discarded", { message })
+   * —— 只有 message，没有 agent、也没有 session。0.2.4 及更早读的是 payload.agent，
+   * 于是 handler 在真实宿主上永远在第一行 return：定时器不撤、日志不写。
+   * 单测又用自造的 { agent, message } 形状喂它，所以 65 例全绿也覆盖不到这个失效。
+   * 现在按 message.id 反查持有该在途 id 的会话状态，不再依赖载荷里的 agent/session。
    */
   const onInboxDiscarded = (payload) => {
     try {
-      const agent = (payload && payload.agent) || payload;
-      const session = agent && agent.session;
-      if (!session) return;
-      const s = stateLookup(session);
-      if (!s) return;
-      const message = payload && payload.message;
+      const message = payload && payload.message ? payload.message : payload;
       const id = message && typeof message.id === 'string' ? message.id : '';
-      if (id === '' || s.nudgeMessageId === null || id !== s.nudgeMessageId) return;
-      clearTimer(s, 'nudge discarded by host');
-      clearNudgeInFlight(s, 'discarded by host');
-      log('nudge DISCARDED by host before claim [' + tag(session) + ']');
+      if (id === '') return;
+      let hit = 0;
+      for (const [sid, s] of stateById) {
+        if (s.nudgeMessageId !== id) continue;
+        clearTimer(s, 'nudge discarded by host');
+        clearNudgeInFlight(s, 'discarded by host');
+        log('nudge DISCARDED by host before claim [' + shortId(sid) + ']');
+        hit += 1;
+      }
+      if (hit === 0) {
+        log('inbox discarded: message ' + id.slice(0, 8) + ' is not an in-flight nudge -> ignored');
+      }
     } catch (err) {
       log('agent/inbox/discarded handler error: ' + errText(err));
     }
@@ -1277,19 +1455,21 @@ export function apply(ctx, config) {
             // 仍可能认领那笔「已超时」的消息 —— 它进转录后开出的照样是补写回合。
             // 不认它，下一个空回合就会被当成真空回合再补一笔（连环补写）。
             const late = !matched && typeof data.id === 'string' && s.guardIds.indexOf(data.id) >= 0;
-            // 非「晚到」的情形都清在途标记（与旧版一致）：对上 id 说明它已被消费；
-            // 对不上说明队列已经往前走了（上一进程遗留/重放），这笔补写也不会再被认领。
-            // 只有晚到认领例外 —— 它可能是旧 id，不该顺手抹掉新一笔的在途状态。
-            if (!late) clearNudgeInFlight(s, null);
-            // 关键：只有真的对上 id 才算「补写回合」。
+            // 关键：只有真的对上 id（或晚到认领）才算「补写回合」。
             // 旧版把 matched 只写进日志、然后无条件置 awaitingGuardTurn，于是任何
             // 同来源但 id 不符的消息（上次进程遗留、重放、另一实例写入）都会被误认，
             // 导致下一个真正的空回合被判成「连环补写」而静默跳过。
             if (!matched && !late) {
+              // 0.2.5 修：这里**不再清在途标记**。旧版在早退之前无条件 clear，
+              // 于是同进程任一插件只要 append 一条 source.kind=plugin:turn-recovery
+              // 且 id 随意的消息，就能把在途标记抹掉 → 下一个空回合多补一笔
+              // （多一轮模型唤醒与费用）。真正「队列已前进」由 120s 认领超时兜底。
               log('guard-kind message seen but NOT ours (id mismatch/expired) -> ignored ['
                 + tag(session) + ']');
               return;
             }
+            // 只有对上 id 时它才算被消费；晚到认领是旧 id，不该抹掉新一笔的在途状态。
+            if (matched) clearNudgeInFlight(s, null);
             s.awaitingGuardTurn = true;
             stats.claimed += 1;
             log('guard message claimed' + (late ? ' (LATE, from guardIds)' : '')
@@ -1305,6 +1485,10 @@ export function apply(ctx, config) {
           // 0.2.0 用「后台黑名单 + 未知即前台」，宿主每加一个通知来源就可能让补写
           // 被静默取消；白名单把默认值改成「不认识就当背景」，漏取消由 turn/start 兜底。
           const form = source && typeof source.form === 'string' ? source.form : '';
+          // 记下本回合是谁发起的：turn/end 的来源闸门读它（见 nudgeSources）。
+          // form:'notice' 是宿主的通知形态，不算「有人说话」，但它的 kind 仍可能
+          // 恰好是 user —— 那种情况不覆盖 turnOrigin，避免把通知当成人类回合。
+          if (form !== 'notice') s.turnOrigin = kind;
           // form:'notice' 是宿主的通知形态（tool-jobs / action-cards / plan-mode /
           // tool-goal 都用它）：无论 kind 叫什么，它都不是人在说话。
           if (form !== 'notice' && cfg.foregroundKinds.has(kind)) {
@@ -1316,7 +1500,14 @@ export function apply(ctx, config) {
         if (event.type === 'assistant/message') {
           const message = data.message;
           if (!message || message.role !== 'assistant') return;
-          if (typeof data.turn === 'number' && s.turn !== data.turn) resetTurnCounters(s, data.turn);
+          if (typeof data.turn === 'number' && s.turn !== data.turn) {
+            // 0.2.5：turn/start 见到过、但它的 turn 不是数值时，s.turn 仍是 null；
+            // 这里若走 resetTurnCounters 会把 sawTurnStart 一并清成 false，于是整个
+            // 回合被误判成「中途加载」而跳过判定（日志与热加载同形，排障会跑偏）。
+            // 只补记 turn 号、保留 sawTurnStart。
+            if (s.sawTurnStart && s.turn === null) s.turn = data.turn;
+            else resetTurnCounters(s, data.turn);
+          }
           const seen = inspectMessage(message);
           s.assistantMessages += 1;
           s.visibleChars += seen.chars;
@@ -1350,6 +1541,9 @@ export function apply(ctx, config) {
 
         const sawStart = s.sawTurnStart === true;
         const empty = !s.visibleNonText && s.visibleChars < cfg.minVisibleChars;
+        // 回合已结束：来源标记取一次就清，避免跨回合残留把上一回合的来源当成这一次的。
+        const turnOrigin = s.turnOrigin;
+        s.turnOrigin = '';
         stats.turns += 1;
         if (empty) {
           if (kind === 'completed') stats.emptyCompleted += 1;
@@ -1375,6 +1569,15 @@ export function apply(ctx, config) {
           log('empty turn but kind=' + kind + ' -> no nudge');
           return;
         }
+        // 来源闸门（0.2.5）：只给「人类发起」的回合补写。社交桥等来源的会话
+        // 一旦被补写，模型输出可能被桥接器转发给第三方联系人 —— 那是用户没有
+        // 授权的对外发言，必须默认拒绝；需要时用 nudgeSources 显式放开。
+        const allowedOrigins = cfg.nudgeSources || cfg.foregroundKinds;
+        if (turnOrigin !== '' && !allowedOrigins.has(turnOrigin)) {
+          log('empty turn but origin=' + turnOrigin + ' not in nudge sources -> no nudge ['
+            + tag(session) + ']');
+          return;
+        }
         if (wasGuard) {
           log('previous turn was already a guard turn and still empty -> stop chaining');
           return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-turn-recovery",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "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",