dsh-vibe-math 2.4.1 → 2.6.0

package/docs/AUDIT-CHECKLIST.md

@@ -95,7 +95,7 @@
 - [ ] 人设里写的路径/模式名（`Formal/Lib`、`off|encourage|require`）是否与实现中的字符串**逐字**一致？
 
 `audit-persona-surface.test.mjs` 把上述各条变成断言（"未文档化工具"用**显式快照**表示：
-新增工具必须主动改快照、或在 persona 里写清）；`audit-persona-sensitivity.mjs` 用 11 条探针
+新增工具必须主动改快照、或在 persona 里写清）；`audit-persona-sensitivity.mjs` 用 16 条探针
 证明这套断言真的会变红。**v2.3.0 修的就是这一类缺陷**：三个 `*_lean_*` 工具无条件注册，
 而 v2/v3/v4 的 persona 从未列出它们（只有 v5 列了），v4 的 `vibe_v4_set` 参数表也漏了
 `formalVerify`/`leanCommand`/`leanArgs`/`leanTimeoutMs`——当时**所有既有套件全绿**。
@@ -166,8 +166,14 @@ v2/v3/v4/v5 是**同构实现**（同一份契约、四份独立代码，刻意
 ### 1.9 工具参数 schema：文档写了 ≠ 工具收得下
 
 §1.6 查的是"persona 里有没有写"，这一节查**工具的参数 schema 收不收得下**。本仓库所有工具 schema 都由
-`objParams` 收口，并以 `additionalProperties:false` **关闭**：schema 没列出的键会被任何遵守 schema 的
-provider **直接拒绝**。于是"提示词/规格/状态表都写着这个参数"完全可以在**功能根本打不开**的同时全绿。
+`objParams` 收口，并以 `additionalProperties:false` **关闭**。**但"关闭"的强度取决于注册路径**（v3 审计 M5
+的更正，Round B 复核扩大）：只有走宿主 `defineTool` 的工具，宿主才会用该 schema 校验实参、把未列出的键
+**直接拒绝**；`tools.register`（裸 `ToolDefinition`）只把 `parameters` 生成给模型的 schema，宿主**从不校验实参**，
+`additionalProperties:false` 在那里只是给模型看的**文档**。**四套预设全部走裸注册**
+（`grep defineTool vibe-math-v{2,3,4,5}.js` → 0 命中；`tools.register` 各 1–3 处），所以"schema 与参数层不一致
+就静默成功（fail open）"对**每一套**都成立，不只是 v3。最典型的反例是 `vibe_math_setup` 公布 `mode`、而
+`vibe_math_set_params` 的 schema 里一度没有它：模型看不到这个键，写给它却仍会被 `sanitizeParams` 收下
+（该键已补进 schema，两条注册路径的键集现在一致）。
 
 - [ ] 每个"可调参数"是否同时出现在：**设置工具的参数 schema**、发现面（`vibe_math_setup` 返回的
       `PARAM_SCHEMA` / v4·v5 的 status 参数表）、`<vibe root>/*setting.json` 模板、以及 persona 参数表？
@@ -190,18 +196,30 @@ provider **直接拒绝**。于是"提示词/规格/状态表都写着这个参
 
 测试和脚本"在我机器上是绿的"不等于它们能跑。**真实事故（2.3.13 归档时发现）**：5 个测试/脚本把
 本机绝对路径写死在源码里（`D:/wd/vibemath开发/...`、`C:/Users/admin/...`），其中
-`audit-fuzz-helpers.mjs` **是随包发布的**——对任何用户都跑不了，而仓库里从来没人发现，
-因为作者机器上它恰好是对的。
+`audit-fuzz-helpers.mjs` 当时**是随包发布的**——对任何用户都跑不了，而仓库里从来没人发现，
+因为作者机器上它恰好是对的。（那些路径后来都改成由 `import.meta.url` 推导；Round B 复核：`tests/`
+下已经没有任何真实的写死盘符路径，而且 `audit-fuzz-helpers.mjs` **现在也不再随包发布**——
+它不在 `package.json` 的 `files` 里，也不在 `npm pack --dry-run --json` 的清单里。）
 
 - [ ] 每个文件路径是否都由 `import.meta.url` / `npm root -g` / 环境变量**推导**出来，
       而不是写死盘符或用户名？（推导不出时应当**报出所有试过的候选路径**，而不是静默跳过。）
 - [ ] 文件被移动/改名后，**引用它的每一处**是否都跟着改？（包括：`package.json` 的 `files`、
       `run-tests.mjs` 这类 runner、守卫里按名字读套件的表、文档里的命令行、README 链接。）
+- [ ] 新增/改名 `tests/` 下的脚本后，确认 **`run-tests.mjs` 真的收集了它**：runner 收集 `tests/` 下
+      **所有** `.mjs`（`*.test.mjs` 是套件，其余是探针），只有登记进 `NEEDS_ARGS` 的脚本才会被跳过，
+      而那个登记会在**开发检出**（存在 `.git`）里被逐项校验——条目失效就直接报错退出，所以改名不能
+      悄悄把一条守卫踢出发布门禁。参数变体（同一脚本跑多次，如 `audit-registration.mjs` 四个预设）走
+      `VARIANTS`。
 - [ ] 命令行/相对链接是否需要**从仓库根执行才成立**？写清楚起点（如 `node tests/run-tests.mjs`），
       别留一个照抄就报"找不到文件"的用法行。
 - [ ] **搬动之后必须有不依赖"跑绿了"的证据**：① 每个套件的断言条数与搬动前**逐项相同**；
       ② 建一个 `git worktree` 拿改动前的检出，同一套件在两种布局各跑一遍，归一化路径/临时目录/耗时后
       **逐行比对**（`_oneoff/layout-invariance.mjs`）；③ 相对链接扫描 0 失效（`_oneoff/scan-links.mjs`）。
+- [ ] 讲"全套件 / 门禁 / 多少次全绿"时，是否区分了**随包发布面**与**仓库**？`package.json` 的 `files`
+      只发 `tests/` 的 **18 项**（其中 `.test.mjs` **10** 个），完整门禁（`node tests/run-tests.mjs`，
+      Round B 起 **57 项 = 39 套件 + 18 探针/变体**）只在开发检出里成立。两边的清单见
+      `docs/test-timing.md` §1.1；发布物里的 runner 会把缺失/跳过项**打印出来**（不会静默少跑），
+      所以"安装用户照文档跑得到全套件"这类说法必须避免。
 - [ ] **runner 本身也要跑一遍**：直接跑套件通过 ≠ 并行 runner 通过（2.3.13 就出现过
       "26 个套件直接跑全绿、`run-tests.mjs` 因为按裸文件名 spawn 而全红"）。发布门禁必须包含 runner。
 
@@ -353,8 +371,9 @@ provider **直接拒绝**。于是"提示词/规格/状态表都写着这个参
 ## Upgrade
 ```
 
-- [ ] 两个 H1 都在；**英文那份的 H1 必须含 `English`**（发布门禁阶段 1c 会检查）；
-- [ ] 中文部分 ≥ 150 个汉字（门禁同阶段检查），英文部分不得残留未翻译段落；
+- [ ] 两个 H1 都在；**英文那份的 H1 必须含 `English`**（人工检查：本仓库**没有任何 CI 工作流**，
+      `scripts/` 只有 `build-preset-rows.mjs`，不存在所谓的"发布门禁阶段 1c"）；
+- [ ] 中文部分 ≥ 150 个汉字（同样人工检查），英文部分不得残留未翻译段落；
 - [ ] 每条变更都回答"**对使用者有什么影响**"——不写内部编号、探针名、断言条数；
 - [ ] 「兼容性」明确回答：四套预设的字节/行为是否变化、参数与工具面是否变化；
 - [ ] 「升级」给出可直接复制的命令（`npm i dsh-vibe-math@latest`；若 profile 里把版本钉死了，

package/docs/COMPAT-AUDIT-ROUND3.md

@@ -73,7 +73,22 @@ DSH 0.1.7 起 agent preset **只**由组合行声明；`$DSH_HOME/.agent-presets
 
 宿主的 `CommandResult` 联合是 `{kind:'success',text?} | {kind:'error',text}`；四套预设的 `/vibe`、`/v4`、`/v5`
 在**所有失败路径**上都返回 `{kind:'success', text:'{"ok":false,…}'}` → UI 永远显示不出"这条命令被拒绝了"。
-修复：按 dispatch 结果自身的 `ok:false` 返回 `kind:'error'`（该联合在 0.1.5 上同样存在，故旧线安全）。
+
+**更正（据实收窄）：这条修复不是一次"全仓"修复，而是分两批落地的，本节初稿把"打算做的"写成了"已经做完的"。**
+
+- **2.4.0（`cc0c220`）只改了 v2 与 v3**（`vibe-math-v2.js` / `vibe-math-v3.js` 的命令 handler）。当时 v4 与 v5 的
+  handler 仍然无条件 `return {kind:'success', text:JSON.stringify(r,null,2)}`（各自的"无 session"分支也返回
+  `kind:'success'`）——所以"四套都修了"在 2.4.0 这个提交上是不成立的。
+- **v4 与 v5 在 round-A（`8ec5a9c`）才各自补上同一形状**：v4 的命令 handler 改成
+  `const failed = !r || r.ok === false || (r.ok === undefined && !!r.error)` → `{kind: failed?'error':'success'}`；
+  v5 改成 `const failed = r !== null && typeof r === 'object' && r.ok === false` → 同样三元返回，并把"无 session"
+  分支一并改成 `kind:'error'`。判据：`git log -G "kind:\s*'error'" -- vibe-math-v4/vibe-math-v4.js`（及 v5 同）
+  **只命中 `8ec5a9c`**；round-C（`4eb3175`）与 round-D（`0dc6ee3`）都没有再碰这两个 handler（前者的 v4 hunk 在
+  1354/1854 行，后者的 v5 hunk 止于 4564 行，均在命令 handler 之外）。
+- **仓库内的回归证据是 round-C（`4eb3175`）补进来的**：`tests/host-failure-paths.test.mjs` 在该提交首次入库，
+  它断言 `/v4 set` 未知键、`/v4` 未知子命令与 `/v5` 未知子命令都返回 `kind:'error'`。round-D（`0dc6ee3`）只是
+  把"本节仍把 `/v4` 的修复说成全仓，需据实收窄"记进了待办，没有改代码。
+- 该联合在 0.1.5 上同样存在，故旧线安全。也就是说：**"四套最终一致"成立，"四套一次修完"不成立**。
 
 ### G-9 文档、镜像与工具描述与实现不符
 

package/docs/final-paper.md

@@ -0,0 +1,171 @@
+# 最终论文（final paper）——四套预设的统一契约
+
+> **这是随包发布的绑定契约。** v2 / v3 / v4 / v5 四个预设的 final-paper 参数、命令、触发时序、
+> 产物与守卫都以本文为准；`实现方案.md` 与工具描述是它的实现说明，冲突时以本文为准。
+>
+> 本文由**用户已确认的规格**（仓库外的 `_oneoff/spec-final-paper.md`）与其后的**设计审计修订**
+> （`_oneoff/spec-final-paper-v2-amendments.md`）合并而成。两份原始文件不在发布物里，所以契约
+> 现在落在仓库内；两者冲突处以**修订**为准，合并时不做美化——修订推翻 v1 的地方在下面写明。
+>
+> 实现位置：v2/v3 的 paper 段（`/vibe paper`）、`vibe-math-v4.js` 的 paper 流程（`/v4 paper`）、
+> `vibe-math-v5.js` 的 paper 流程（`/v5 paper` + `vibe_v5_paper` / `vibe_v5_finalize_paper`）。
+
+## 1. 一句话
+
+四个预设都**默认开启**最终论文：当各自的收口信号命中时，**先进入 paper 阶段，论文完成（或降级结束）
+之后才把这次 run 标记为完成**。论文只整理已有证据，产物落在 `Paper/<运行或研究所 id>/`，
+文本版永远交付，PDF 只在宿主真的检测到 LaTeX 引擎时才尝试编译。
+
+## 2. 参数
+
+参数进入各预设既有的参数体系（`setParams` 工具的 schema + 帮助文本 + 命令 hint），默认值如下：
+
+| 参数 | 类型 | 默认 | 作用域 | 说明 |
+|---|---|---|---|---|
+| `finalPaper` | boolean | `true` | 四套 | 收口时是否**自动**撰写最终论文。`false` 只关自动触发，手动命令仍可用（返回里会写明"自动已关闭"） |
+| `paperFormat` | enum `both`\|`md`\|`tex` | `both` | 四套 | 产出哪几种文本版本；`md` 不产出 tex、因此跳过编译，且**不得**报"缺 tex"警告 |
+| `paperLanguage` | enum `zh`\|`en` | `zh` | 四套 | 论文语言，同时决定 LaTeX 模板（`ctexart`/`article`）与引擎优先顺序 |
+| `paperCompilePdf` | boolean | `true` | 四套 | 检测到 LaTeX 时是否编译 `paper.pdf` |
+| `paperLatexCommand` | string | `''` | 四套 | 强制指定**一个**引擎可执行文件；空 = 按语言自动探测。指定但解析不到时按"未检测到"降级 |
+| `paperEditor` | enum | v4 `office`；v5 `academician` | **仅 v4/v5** | 定稿代表。v4：`office`（会话根/人类侧）或 `resident:<id>`；v5：`academician` 或 `office`（见 §7） |
+
+归一化：**枚举**的非法值一律回退到上表默认值（绝不回退到更强的档位）；**未知键不会直通参数层**
+（v2/v3 的参数归一化只遍历已知默认键，v4 把被忽略的键列在返回的 `ignored` 里，v5 的 set-schema 是闭集，
+新键必须同时进闭集与枚举校验，参照 `quorumMode`）。**boolean** 接受 `true`/`false`；v4/v5 另外接受
+`1/0/yes/no/on/off` 等拼写——命令行的 `k=v` 传的是原始字符串，`'false'` 必须真的变成 `false`，
+不能保持真值；v2/v3 只接受真正的 JSON boolean，其余值回退默认。
+
+## 3. 自动触发：用**真实的**收口信号，且先论文、后完成
+
+各预设的收口信号以代码中的精确分支为准（v1 规格曾写成"更强的完整性判据"，那会永不触发；此处按修订修正）：
+
+- **v2**：严格终止（任务清空且无在途）。**「论文撰写」子代理本身不计入"在途"**——否则撰写者会阻止收口。
+- **v3**：`checkTermination` 的完整收口分支；真实的完整性判据是 `leftoverVerify`（不是"`Verified/` 全覆盖"）。
+- **v4**：一致性会议的**一致停止票**（`finalizeMeeting` 的 `allSolved` 分支）；该分支会忽略并清空待验证对象与邮箱。
+- **v5**：`checkSolved` 在**每一次解题票**上判定（不要求 verify/meeting 前置）。
+
+**时序（修订 §A，HIGH）**：论文阶段必须发生在"标记完成"**之前**。收口分支一旦同时置
+`running=false; autoDone=true`（v4）或 `phase='solved'`（v5），`startMeeting` / `wakeIfIdle` /
+`onResidentEnd` / `scheduleNext` 都会拒绝，团队就再也无法合写与互审。因此：
+
+- v4 在 `finalizeMeeting` 的 `allSolved` 分支内、v5 在 `checkSolved` 与 `finishRun` 之间**拦截**，
+  先进入 paper 阶段，用既有的会议/唤醒机制完成合写与审稿，论文结束（或降级结束）后才真正置完成标志；
+- v2/v3 **在停止翻转之前**派遣「论文撰写」子代理（`scheduler.running=false` 之后 `scheduleTick()` 是空操作，
+  而且 v2/v3 没有激活上限处理，被拒/失败的撰写者会静默消失）。
+
+**幂等**：同一 run 只写一次。`paper.meta.json` 记 `finalizedAt`；重复触发**只补写缺失产物**。
+`finalPaper=false` 只关闭上面这条自动路径。
+
+## 4. 手动命令
+
+| 预设 | 命令 | 说明 |
+|---|---|---|
+| v2 / v3 | `/vibe paper [lang=zh\|en] [format=both\|md\|tex] [force]` | 单作者流程 |
+| v4 | `/v4 paper [lang=zh\|en] [format=both\|md\|tex] [editor=office\|resident:<id>] [force]` | 团队流程，`editor=` 只作用于本次 |
+| v5 | `/v5 paper [lang=zh\|en] [format=both\|md\|tex] [editor=office\|academician] [force]` | 团队流程；`editor=office` 走人工定稿路径（§7） |
+
+- 命令行覆盖只作用于**本次**调用，不写回持久参数（v5 的 `editor=` 是一次性的）。
+- 非法参数一律 `kind:'error'`（绝不静默成功）；`force` 重写已定稿的论文。
+- v5 另有工具入口 `vibe_v5_paper`（与命令同义）与 `vibe_v5_finalize_paper`（所办定稿）。
+
+## 5. 产物
+
+目录：`Paper/<运行或研究所 id>/`（id 经各预设既有的 `slugify`/`safeId`/`idSafe` 归一化，
+所有路径经同一个 `Paper/` 构造器，只写这个目录内，不污染 `Verified/`、`State/`）。
+
+| 文件 | 何时出现 |
+|---|---|
+| `paper.md` | `paperFormat` 含 `md`（`both`/`md`） |
+| `paper.tex` | `paperFormat` 含 `tex`（`both`/`tex`） |
+| `paper.pdf` | 仅在编译器**真的跑通**时出现 |
+| `paper.meta.json` | 总是：参数、触发原因、运行 id、`finalizedAt`、编译状态与引擎、v5 的咨询计数等 |
+| `paper.log.md` | 总是：谁写了什么、谁提了什么意见、如何采纳（人读审计链） |
+
+宿主 fs 只支持**文本写**（没有 `writeBytes`），所以 `paper.pdf` **只能由编译器子进程**在论文目录内产生，
+插件只做存在性校验，绝不自己写二进制，也**绝不覆盖已存在的 pdf**。
+
+## 6. 论文骨架（四套一致，9 节）
+
+1. 标题、作者（预设名 + 运行/研究所标识）、日期、摘要（原问题 + 主要结论）
+2. 引言与问题背景（原问题的完整陈述）
+3. **原问题的完整解法**（最终答案 + 完整推理链）
+4. **已检验通过的命题**（逐条列出，含判定为真的估计值与证据来源）
+5. **已解决的子问题 / 中间成果**
+6. **创造或发现的有价值之物**：方法、理论、思想、有价值经验、数学理解
+7. **规律总结**（从上述条目归纳出的可复用规律）
+8. 讨论、局限与展望
+9. 附录：证据与文件索引（`Verified/`、`Logs/`、关键卡片路径）
+
+写法要求：只写有证据支撑的内容；**未决 / 被否证的条目必须显式标注**；不得编造。
+
+## 7. 写作流程
+
+**v2 / v3（单作者）**：派遣一名专职「论文撰写」子代理，输入 = 汇总材料（命题 / 子问题 / 成果 /
+规律线索 + 证据索引），产出 = 完整 md 正文（含 tex 用的结构标记）；插件负责落盘 md/tex 与编译。
+
+**v4 / v5（团队合写）**：
+
+1. 各自写自己负责的部分（v4：各 resident 写自己库里的内容；v5：各常驻研究员/院士写自己负责的部分）；
+2. **合并**（去重、统一术语、统一符号）；
+3. **互检/审稿**：至少一轮交叉审阅（每人审他人的部分，指出问题并优化）；
+4. **定稿**：定稿代表按 `paperEditor` 梳理成最终稿；
+5. **一致认同**才定稿：所有参与成员明确表示"可交付"；有反对则继续迭代（有轮次上限，超限记警告并把分歧写进附录）。
+
+定稿代表：
+
+- **v4**：`paperEditor` 默认 `office`（= 会话根 / 人类侧；`facilitator` 不在编制里、没有 LLM，不能当作作者），
+  另可选 `resident:<id>`。指定的 resident 已离职时**降级到 office** 并在 `paper.meta.json` 与 `paper.log.md` 记明。
+- **v5**：`paperEditor` 默认 `academician` —— 这是**无人值守也能完成**的路径（所办是根会话，没有唤醒路径，
+  自动收口触发必须用院士）。`office` 只在手动 `/v5 paper editor=office` 时可用，并且
+  **所办必须先与全所交流、商讨、优化、审查**：至少 1 条所办消息（`vibe_v5_message`）**且**至少 1 次会议
+  （`vibe_v5_meeting`），结论写进定稿说明，然后调用 `vibe_v5_finalize_paper`。
+  两个计数记在 `paper.meta.json`；缺一即 `V5_PAPER_CONSULT_REQUIRED`（不是静默跳过）。
+
+## 8. LaTeX 检测、编译与降级
+
+- **检测**走 `subprocess.resolveExecutable`：`paperLatexCommand` 非空时**只用它**（不猜）；
+  空则按语言探测 —— 中文 `xelatex` → `latexmk` → `pdflatex` → `lualatex` → `tectonic`
+  （xelatex 对 CJK 开箱可用），英文 `pdflatex` 优先，其余同理。
+- **编译**在论文目录内执行、`-interaction=nonstopmode`、跑两遍（`latexmk`/`tectonic` 用各自参数）。
+- **先修复、后降级**（有收敛上限）：换引擎重试 → `nonstopmode` 重跑 → 换最小模板
+  （`ctexart` / `article`）再试一次；到达上限就**保留 tex+md**，`paper.meta.json` 记
+  `compile: 'failed'`（或未检测到时的 `'not-detected'`），**警告 + 上报**，但**不阻塞定稿**、
+  **不抛错**、**不覆盖已有 pdf**，也绝不改写论文内容。
+- `paperFormat=md` 时根本不产出 tex，编译直接 `skipped`，不得产生"缺 tex 无法编译"的警告。
+- tex 模板：中文 `ctexart`（xelatex），英文 `article`；只用常见宏包（`amsmath`、`amssymb`、`amsthm`、
+  `geometry`、`hyperref`、`longtable`、`booktabs`）；转义所有 `_ % & # $ { } ~ ^ \`。
+- 记录：规格确认时本机**没有任何 LaTeX 引擎**，所以真机走的是"未检测到 → 只交 tex+md"分支；
+  编译成功 / 修复后成功 / 持续失败三条路径由守卫里的**假编译器**覆盖（见 §10）。
+
+## 9. 幂等与可审计
+
+- 幂等键 = **run id + `finalizedAt` + 逐产物存在性检查**（不使用多文件稳定哈希）；
+  重复触发只补写缺失产物，`force` 才重写。
+- v2 的收口判据含 `agentRegistry=={}` ⇒ 撰写子代理被排除在收口判据之外（§3）；v3 在触发前已释放项目锁，
+  因此论文落盘要**原子 + 幂等**（可加 paper 作用域锁），避免两个会话写同一棵树。
+- 每次触发、每次派遣、每次编译、每次降级都追加 `paper.log.md`，并在活动日志里留一条。
+
+## 10. 守卫与验证要求
+
+每条不变式都要有断言，且要么有灵敏度探针证明它会变红，要么在探针里写明为什么不可达：
+
+- 参数默认值 / schema 存在性 / 非法值回退；五个（v4/v5 六个）参数同时出现在工具 schema 与帮助文本里；
+- 触发判定的正负用例：未收口不触发、收口触发、`finalPaper=false` 不触发、重复触发幂等；
+- 内容生成：假 LLM/假成员回应驱动，断言 md/tex 两版产出、9 节骨架齐全、证据索引存在、未决项被标注；
+- 编译分支：假编译器覆盖"成功 → pdf""失败 → 修复后成功""持续失败 → 降级 + 警告"三条路径；
+  真机无 LaTeX 时断言走"未检测到"分支且不报错；
+- 路径与越权：只写 `Paper/<id>/` 内、id 归一化（防路径逃逸）、与 `Verified/`/`State/` 不互相污染；
+- 命令：`/vN paper` 的参数覆盖、`force` 与非法参数 `kind:'error'`；
+- 团队流程（v4/v5）：断言"各部分 → 合并 → 互审 → 定稿"的消息序列；`paperEditor` 两种取值都可用；
+  v5 选 `office` 时**确有**交流与会议记录（负用例：未咨询就定稿必须被拒），未达成一致认同时不定稿。
+
+现有守卫：`tests/v4-final-paper.test.mjs`（v4 团队流程与产物）、`tests/e2e-v5-round2.test.mjs`
+（v5 的手动/自动路径与所办咨询门）、`tests/v2-fix-probes.test.mjs` / `tests/v3-fix-probes.test.mjs`
+（v2/v3 的收口派遣与降级）、`tests/audit-persona-sensitivity.mjs`（提示词面必须随新命令/工具更新）。
+
+## 11. 纪律
+
+- 写域按预设切分，同一文件只有一个写者；实现者**不提交**（由 Lead 统一提交并跑门禁）。
+- **不得编造论文内容**：论文只整理已有证据，未决/被否证的条目显式标注。
+- 成本纪律：只跑本预设相关套件 + 自建聚焦探针；全量 `run-tests`、`audit-formal-sensitivity`、
+  `e2e-v4-fixes` 等慢脚本留给轮末门禁（见 `docs/test-timing.md`）。

package/docs/release-notes/RELEASE-NOTES-2.5.0.md

@@ -0,0 +1,173 @@
+# dsh-vibe-math 2.5.0 — 发布说明（中文）
+
+> 上一版：2.4.1。本版是**深度审计后的修复版本**：四套预设的提示词、工具面、组合声明与数据格式未做破坏性变更，
+> 但修复了多处"看起来能跑、实际目标功能不成立"的缺陷（含三处会丢数据或让运行停摆的问题），并新增多项守卫。
+
+---
+
+## 概览
+
+- 本轮对 v2/v3/v4/v5 四套预设 + 安装器 + 全部守卫做了多轮独立审计与交叉证伪（审计结论：**所有宿主接口/工具/命令调用在 DSH 0.2.0-rc.2 上均存在且调用形状正确**；问题集中在目标功能与内部逻辑）。
+- 修复了 **3 处会造成实际损害的问题**：v5 的状态文件会被空研究所覆盖、v2 的验证日志文件名可越出项目目录、v4 的邮箱投递失败会让调度器永久停摆。
+- 还修掉 **v4 的"真实 /compact"从未生效**、**v3 空闲时每 tick 空转派生 planner**、**v3 单票即可写入 `Verified/`**、**v5 同 tick 并发提议会丢提案**等。
+- 在本机 DSH 0.2.0-rc.2 上做了**真实宿主端到端验证**：四个预设正常注册（order 20–23）、零激活警告、组合行线上不再写旧的 `.agent-presets` 目录。
+- 测试与守卫大幅加强：全仓 **38 套件 + 18 探针**全部纳入自动门禁（此前有若干探针未被收集），并修正了一处测试抖动与一处语料非确定性。
+
+## 变更
+
+### 1. 数据安全与"运行不卡死"
+
+- **v5 状态文件不再被覆盖**：状态后端改为**按路径锁存**，读取未成功即**拒绝写入**；对已存在的研究所改为**采纳**而非重置。此前会话里第一次工具调用会锁存默认路径，随后指定研究所的配置会把它覆盖成空研究所。
+- **v2 路径逃逸**：验证日志文件名改用 `safeId` 归一化，`q.id="x/../../../../pwn"` 这类输入不再能把文件写出项目目录。
+- **v4 调度器停摆**：邮箱投递失败的两条路径（立即投递失败、brainstorm 阶段无处重投）都会重排队并在后续 pass 重试，不再出现"心跳已清、永不重试"的静止状态。
+- **v5 队列竞态**：验证队列的追加与取头改为在事件折叠内完成，同一 tick 内两个成员同时提议不再丢提案。
+
+### 2. 目标功能真正可达
+
+- **v4 的 `/compact`**：按 `subagent/start` 载荷认领活动 Agent，真实压缩调用（`compactNow`）首次真正生效。
+- **v2 的"判断命题"链**：为判断问题补种可验证的解法入口，使"问题 → 判断问题 → 验证 → 收口"主线真正跑通。
+- **v3 的空转**：空闲时不再每个 tick 派生 planner（实测由 41 次降到 13 次，并首次出现正常终止）。
+- **v3 的项目锁**：改为**定时器续租**（此前的续租写在 tick 内，单次慢 tick 就会让别的会话无 override 夺锁）。
+- **v3 的最小票数**：要求达到承诺的验证者数量、且**至少 2 票**才裁决，单票不再能把命题写成"已验证·真"。
+
+### 3. 语义与表述对齐（含提示词面）
+
+- **v4 验证契约**：人设与工具描述明确"**只有精确的 1 / 0 是绝对真/绝对假**；介于 0 与 1 之间是模型认为的概率，只有全 1 或全 0 才算全体一致，否则取**平均概率**更新布尔估计"（代码分支未改，此前示例与说明不足）。
+- **v5 的 m-vote 表述**：文档/人设/README 改为与计票代码一致——"**至少 m 张布尔票且没有任何一张反对票**，默认名册下退化为全体一致"，并删除"比全体一致更易收敛"这一**不实**说法。
+- **四套同级**：v2/v3 改称"经典"、v4/v5 为"实验性"，npm 描述、选择器描述、人设文本、v3 设计文档、安装段顺序全部对齐（此前只有 README 改了）。
+- **v2 的侧信道**：推送汇报的消息来源由未声明的 `kind:'plugin'` 改为已声明的 `kind:'user'`；`solver/verifierMaxToolCalls` 改为如实标注为"仅提示、不强制"。
+- **v5 的调用者授权**：`isOffice` 不再把空身份当所办；无法识别身份的成员调用一律拒绝（此前一个幽灵身份可以改优先级、甚至删掉真实任务）。
+- **v5 的工具描述**：补齐会议 `kind` 枚举与 `target`、说明 `hire.term`。
+
+### 4. 安装器、声明与守卫
+
+- **形态判定改能力差**：旧线上"组合行 registry 包"根本不存在（已用 npm 元数据与包内容证实：0.1.6-alpha.2 无 `@deepseek-ai/dsh-agent-preset`，0.1.7-rc.2 才有），判定改用 `register` 能力，并新增可证伪守卫（把该行改回 `list` 只有新守卫会红）。
+- **声明行补宿主 group 标记**：8 处嵌套 `!!js` 现在以表达式形式保留给 preset 作用域，而不是在声明域被就地求值。
+- **安装器更安全**：preset 文件改**原子写**；删除 preset 前**先备份**用户改动过的文件；**读不出来**的文件不再被无备份删除；状态文件内容不变则跳过写、写失败会告警、`listBundles` 有超时兜底。
+- **守卫扩面**：`run-tests` 现在收集**全部**测试与探针（此前有 2 套红探针被静默漏收），修正了一处测试抖动（v4 会议用例）与一处语料非确定性（v3），并新增安装器/声明/命令失败路径/宿主失败路径等守卫。
+
+## 兼容性
+
+- **DSH 支撑窗口不变**：`0.1.2-alpha.4 … 0.2.0-rc.2`；组合行（≥0.1.7）与目录（≤0.1.6）两条线都保留，且新增能力差判定后旧线不会再被误判。
+- **数据与目录结构不变**：`State/<研究所>.v5state.json`、项目布局、镜像文件位置均照旧；无需迁移。
+- **提示词**：除"v4 验证契约/闭包规则说明、v5 m-vote 表述、v2/v3/v4 人设补一行一致的闭包规则、v5 工具描述补字段"之外未改动；语料已按当前四套重新生成。
+- **参数默认值**：未变（v2 每个待验证对象最多 `max(2, min(verifierCount, maxParallelThreshold-2))` 个验证者，默认配置下为 2；工具调用上限仍为提示性）。
+
+## 升级
+
+```sh
+npm i dsh-vibe-math@latest
+```
+
+桌面版在「设置 → 插件」里更新；命令行 profile 用 `dsh plugin --profile <你的 profile> add dsh-vibe-math@latest`，随后重启 DSH。
+
+---
+
+# dsh-vibe-math 2.5.0 — Release Notes (English)
+
+> Previous: 2.4.1. This release is the outcome of a deep, independently cross-checked audit: the four
+> presets' prompts, tool surface, composition declarations and data formats have no breaking change, but
+> several defects that "looked like they worked while the intended function did not" are fixed — three
+> of them could lose data or stall a run — and the guard suite is substantially stronger.
+
+---
+
+## Overview
+
+- Multiple audit rounds with independent falsification covered the four presets, the installer and every
+  guard. Verdict: **every host interface, tool, command and service call exists on DSH 0.2.0-rc.2 with
+  the correct call shape**; the defects were in goals and internal logic.
+- Three fixes prevent real damage: v5's state file being overwritten by an empty institute, v2's
+  verification-log filename escaping the project directory, and v4's scheduler stalling forever after a
+  failed mailbox delivery.
+- Also fixed: v4's "real /compact" never firing, v3 spawning a planner on every idle tick, v3 finalising
+  a proposition on a single vote, and v5 losing a proposal when two members proposed in the same tick.
+- Verified on a **real DSH 0.2.0-rc.2 host**: the four presets register (orders 20–23) with zero
+  activation warnings, and the row line no longer writes the legacy `.agent-presets` directory.
+- Guards grew from 30 to **38 suites + 18 probes**, all collected by the gate (several probes used to be
+  silently skipped); one flaky test and one non-deterministic corpus were fixed.
+
+## Changes
+
+### 1. Data safety and "no run can stall"
+
+- **v5 state file can no longer be overwritten**: the backend latches **per path** and **refuses to
+  write** when the read never succeeded; an existing institute is **adopted** instead of reset. The
+  first tool call of a session used to latch the default path, after which configuring a named institute
+  overwrote it with an empty one.
+- **v2 path escape**: the verification-log filename is normalised with `safeId`, so an id such as
+  `x/../../../../pwn` can no longer write outside the project directory.
+- **v4 scheduler stall**: both failed-mailbox paths (immediate delivery rejection, and the brainstorm
+  phase where nothing retried) now re-queue and retry on a later pass.
+- **v5 queue race**: queue append and head-take now happen inside the event fold, so two members
+  proposing in the same tick can no longer lose a proposal.
+
+### 2. The intended function actually happens
+
+- **v4 `/compact`**: the live Agent is claimed from the `subagent/start` payload, so the real
+  `compactNow` finally fires.
+- **v2's judge-problem chain**: the judge problem now carries a verifiable solution entry, so
+  problem → judge problem → verification → closure really runs.
+- **v3 idle spawning**: no planner is spawned on every idle tick any more (measured 41 → 13) and a
+  normal termination was observed for the first time.
+- **v3 project lock**: renewal moved to a timer (it used to live inside `tick()`, so one slow tick let
+  another session steal the lock without an override).
+- **v3 minimum votes**: the promised verifier count and at least two votes are now required before a
+  verdict; a single vote can no longer write `Verified/`.
+
+### 3. Semantics and wording aligned (including prompt-facing text)
+
+- **v4 verdict contract**: the persona and tool description now state that **only an exact 1 / 0 is
+  absolutely true/false**; anything strictly between is the model's probability of truth, only an all-1
+  or all-0 set is unanimity, and otherwise the **mean** updates the boolean estimate (the code path is
+  unchanged; the example and explanation were insufficient).
+- **v5 m-vote**: docs, persona and README now match the tally — "**at least m boolean votes with no
+  opposing vote**, which degenerates to unanimity on the default roster" — and the false claim that it
+  "converges more easily than unanimity" is gone.
+- **Four peers**: v2/v3 are "classic", v4/v5 "experimental" — the npm description, picker descriptions,
+  persona text, v3's design doc and the install-section order were all brought in line (previously only
+  the READMEs).
+- **v2 side channels**: the push report's message source is the declared `kind:'user'`; the
+  `solver/verifierMaxToolCalls` settings are now honestly described as advisory.
+- **v5 caller authorisation**: `isOffice` no longer treats an empty identity as the office, and tool
+  calls from an unidentifiable caller are refused (a ghost identity could previously change priorities
+  and even delete a real task).
+- **v5 tool descriptions**: the meeting `kind` enum plus `target`, and `hire.term`, are now documented.
+
+### 4. Installer, declarations and guards
+
+- **Mechanism detection by capability**: the row registry package does not exist on the old line
+  (proven from npm metadata and package contents: 0.1.6-alpha.2 has no
+  `@deepseek-ai/dsh-agent-preset`, 0.1.7-rc.2 adds it), so the decision now tests the `register`
+  capability, with a falsifiable guard (reverting that one line turns only the new guard red).
+- **Declaration rows carry the host group marker**: the eight nested `!!js` expressions are preserved
+  for the preset scope instead of being evaluated in the declaring realm.
+- **Safer installer**: preset files are written atomically; a user-edited file is backed up before its
+  preset is dropped; an unreadable file is no longer deleted without a backup; the state file is
+  skipped when unchanged, write failures warn, and `listBundles` has a timeout fallback.
+- **Wider guards**: `run-tests` now collects **every** test and probe (two red probes used to be
+  silently skipped), one flaky test (v4 meetings) and one non-deterministic corpus (v3) were fixed, and
+  new guards cover the installer, the declaration row, command failure paths and host failure paths.
+
+## Compatibility
+
+- **Supported DSH window unchanged**: `0.1.2-alpha.4 … 0.2.0-rc.2`; both the composition-row (≥ 0.1.7)
+  and directory (≤ 0.1.6) lines are kept, and the capability-based verdict means the old line can no
+  longer be misclassified.
+- **No data or layout change**: `State/<institute>.v5state.json`, the project layout and the mirror file
+  locations are unchanged; no migration needed.
+- **Prompts**: unchanged except the v4 verdict-contract/clojure-rule wording, the v5 m-vote wording, one
+  consistent closure-rule line added to the v2/v3/v4 personas, and the added v5 tool-description fields;
+  corpora were regenerated for the current four presets.
+- **Defaults**: unchanged (v2 caps reviewers per target at
+  `max(2, min(verifierCount, maxParallelThreshold-2))`, i.e. 2 on the default configuration; the tool-call
+  limits remain advisory).
+
+## Upgrade
+
+```sh
+npm i dsh-vibe-math@latest
+```
+
+Desktop updates through Settings → Plugins; a CLI profile uses
+`dsh plugin --profile <your profile> add dsh-vibe-math@latest`, then restart DSH.