dsh-vibe-math 2.4.1 → 2.5.0

package/docs/test-timing.md

@@ -8,52 +8,77 @@
 ## 1. 怎么跑（并行是默认）
 
 ```bash
-node tests/run-tests.mjs                     # 全部 *.test.mjs（在 tests/ 下），并行（并发 = min(4, CPU 核数)；命令都从**仓库根**执行）
-node tests/run-tests.mjs --only formal       # 只跑名字含 formal 的套件
+node tests/run-tests.mjs                     # 全部套件 + 全部探针（tests/ 下每个 .mjs），并行（并发 = min(4, CPU 核数)；命令都从**仓库根**执行）
+node tests/run-tests.mjs --only formal       # 只跑名字含 formal 的项（套件与探针一起筛）
 node tests/run-tests.mjs --concurrency=6     # 手动指定并发
-node tests/audit-formal-sensitivity.mjs      # 49 条不变式探针，并行（--concurrency=N / --only=<preset> / --list）
-node tests/audit-persona-sensitivity.mjs     # 11 条提示词面探针（串行，本身只要几秒）
-node tests/audit-prompt-invariants.mjs       # 静态：四套的提示词/工具面不变式 + 扫描器自检（< 0.1s）
-node tests/audit-prompt-invariants.mjs --self-probe   # 证明上面那 157 条不变式真的会变红（5 个自探针）
-node tests/audit-spec-traceability.mjs       # 静态：规格/README ↔ 代码可追溯（< 0.1s）
-node tests/audit-v5-integrity.mjs            # 静态：v5 完整性/理念门禁 + 扫描器解析级自检（≈0.5 s）
+node tests/run-tests.mjs --json              # 机器可读汇总（含 skippedNeedsArgs / devCheckout）
 ```
 
-两个并行 runner 都会打印**每项耗时 + 汇总（wall / sum / speed-up / 最慢几项）**。跑完请读这几行。
+`run-tests.mjs` 的收集规则（Round B 起）：`tests/` 下**每个** `.mjs` 都会被跑——
 
-## 2. 基线（本机：4 核 / 8 GB，Windows，实测）
+- `*.test.mjs` 是**套件**；其余 `.mjs` 是**探针/审计**（灵敏度变异、注册面、自驱动守卫）；
+- 只有登记在 runner 的 `NEEDS_ARGS` 里的脚本才会被跳过（当前只有 `audit-tool-exec.mjs`：它必须带
+  `<preset-js> <tool-name>` 才能跑）。跳过项**每次运行都会打印出来**；在开发检出（存在 `.git`）里
+  该登记失效会**直接报错退出**，所以改名不可能悄悄把一条守卫踢出发布门禁；
+- 需要参数的变体登记在 `VARIANTS`：`audit-registration.mjs` 四个预设各跑一次（裸跑只查 v3）、
+  `audit-prompt-invariants.mjs --self-probe`、以及 `audit-v3-registration-parity.mjs --self-probe`
+  （这条**成功 = 退出码 1**：它注入真实变异并要求守卫变红，runner 用 `expectExit` 表达）。
+
+### 1.1 随包发布 vs 仅仓库（`npm pack --dry-run --json`）
+
+`package.json` 的 `files` 只发 `tests/` 的一个**子集**（发布物共 102 个文件，其中 `tests/` 18 项），
+所以安装用户跑 `node tests/run-tests.mjs` 得到的是子集的结果——runner 会把缺失的跳过项打印出来，
+不会静默少跑：
+
+- **随包（18 项）**：`run-tests.mjs`、`audit-formal-sensitivity.mjs`、`audit-persona-sensitivity.mjs`、
+  `audit-prompt-invariants.mjs`、`audit-spec-traceability.mjs`、`audit-v5-integrity.mjs`、
+  `audit-v5-sensitivity.mjs`、`selfdrive-v5.mjs`；套件 **10** 个：`audit-installer-compat`、
+  `audit-installer-policy`、`audit-persona-surface`、`audit-preset-rows`、`e2e-v5-round2`、
+  `formal-verify-v2`、`formal-verify-v3`、`formal-verify-v4`、`formal-verify-v5`、`prompt-v5-integrity`。
+- **仅仓库（不发）**：其余 28 个套件（v2/v3/v4 的 e2e、`selfdrive-v3`/`v4`、v2/v3 修复探针、
+  `audit-fuzz-helpers` 之外的若干 `audit-*`……）与 7 个脚本（`audit-fuzz-helpers`、
+  `audit-registration`、`audit-roundtrip-idempotence`、`audit-tool-exec`、
+  `audit-v3-registration-parity`、`selfdrive-v3`、`selfdrive-v4`）。
+- 因此**完整门禁只能在开发检出里跑**；发布物里的子集是"用户可自查"的一部分，不是全部证据。
+  （`audit-fuzz-helpers.mjs` 在 2.3.13 时曾随包发布；现在不在 `files` 里。）
+
+## 2. 基线（本机：4 核 / Windows，实测）
 
 | 脚本 | 串行（sum） | 并行（wall） | 实测输出 |
 |---|---|---|---|
-| `tests/run-tests.mjs`（29 个套件） | ≈ 230 s | **≈ 110 s**（并发 4） | 关键路径 = `e2e-v4-fixes` ≈ 96 s |
-| `tests/audit-installer-policy.test.mjs` | ≈ 1 s | — | 在临时 DSH_HOME 里驱动真实安装器（复制 4 套预设 × 2 个版本） |
-| `tests/audit-preset-rows.test.mjs` | ≈ 0.2 s | — | 四个 preset 的声明行（cordis.patch.yml 与生成器逐字节一致、bundle.patch 必须是字符串、行不得用 `ctx.get` 的 `!!js` 门、组合里必须有 present/command-goal/isolate/workflow-ptc；纯静态） |
-| `tests/audit-readme-bilingual.test.mjs` | ≈ 0.2 s | — | 中英 README 的结构/链接/图片/锚点一致性（英文版架构图按 `-en` 变体配对；纯静态） |
-| `tests/audit-diagram-assets.test.mjs` | ≈ 1 s | — | 四张架构图 PNG 必须装得下它自己的画面、四张英文版 SVG 必须存在且正文为英文（解 PNG 与 SVG，纯静态） |
-| `audit-formal-sensitivity.mjs`（49 探针） | 612.0 s | **154.6 s**（并发 4，speed-up x3.96） | 关键路径 = 12 个 v2 探针（每个 ≈32 s） |
-| `audit-persona-sensitivity.mjs`（11 探针） | ≈ 5 s | — | 本身很快，不需要并行 |
-| `audit-prompt-invariants.mjs`（157 条，含 X5–X8b 扫描器自检） | 0.4 s | — | 静态 |
-| `audit-prompt-invariants.mjs --self-probe`（5 探针） | 1.5 s | — | 每个探针 = 一次自我重跑（0.3 s） |
-| `audit-spec-traceability.mjs`（94 条） | 0.3 s | — | 静态 |
-| `audit-v5-integrity.mjs` | ≈ 0.5 s | — | 静态审计（含扫描器自检） |
-| `prompt-v5-integrity.test.mjs` | 1.6 s | — | 虚拟时钟下生成 v5 语料（语料字节稳定；**stdout 里的会议成员顺序仍是运行间随机的**，只有落盘语料是逐字节确定的） |
-
-> 优化前：全量回归 ≈ 5.5 min（串行，`formal-verify-v2` 单独 186 s）；
-> 探针脚本 ≈ **38 min**（49 条串行，其中 12 条 × `formal-verify-v2` 162 s）。
-> 现在：**1.9 min / 2.6 min**。
+| `tests/run-tests.mjs`（**56 项** = 38 套件 + 18 探针/变体） | ≈ 629 s | **≈ 208 s**（并发 4，speed-up x3.02） | `TOTAL 56  PASS 56  FAIL 0  (suites 38 · probes 18)`；关键路径 = `audit-formal-sensitivity` 208 s |
+| `tests/audit-formal-sensitivity.mjs`（49 探针，自带并发 4） | 803 s | **≈ 208 s** | 关键路径 = 12 个 v2 探针（每个 ≈42–60 s） |
+| `tests/audit-v5-sensitivity.mjs`（39 探针，串行） | ≈ 101 s | — | 每条 = 一次被测套件重跑 |
+| `tests/audit-persona-sensitivity.mjs`（11 探针） | ≈ 4.4 s | — | 本身很快，不需要并行 |
+| `tests/audit-prompt-invariants.mjs`（157 条） | ≈ 1.9 s | — | 静态 |
+| `tests/audit-prompt-invariants.mjs --self-probe`（5 探针） | ≈ 7.4 s | — | 每个探针 = 一次自我重跑 |
+| `tests/audit-spec-traceability.mjs`（94 条） | ≈ 0.2 s | — | 静态 |
+| `tests/audit-v5-integrity.mjs` | ≈ 0.6 s | — | 静态审计（含扫描器自检） |
+| `tests/audit-registration.mjs`（4 个预设各一次） | ≈ 1.0 s | — | 裸跑只查 v3，所以 runner 跑四个变体 |
+| `tests/audit-v3-registration-parity.mjs`（+ `--self-probe`） | ≈ 0.3 s | — | 自探针**成功 = exit 1**（变异后守卫必须变红） |
+| `tests/prompt-v5-integrity.test.mjs` | ≈ 2.2 s | — | 虚拟时钟下生成 v5 语料（语料字节稳定；**stdout 里的会议成员顺序仍是运行间随机的**，只有落盘语料是逐字节确定的） |
+| `tests/e2e-v5-round2.test.mjs` | ≈ 3.2 s | — | v5 e2e（含本轮新增的"预置快照不被覆盖""命名研究所被读取""失败轮次"三节） |
+| `tests/host-failure-paths.test.mjs` | ≈ 6.3 s | — | 真实宿主的失败路径（`kind:'error'`、`/v4 set` 键校验、失败轮次不算进展） |
+| `tests/v4-mailbox-stall.test.mjs` | ≈ 7.1 s | — | `sendMessage` 拒绝后必须重投并唤醒（control + treatment 各一个 host） |
+| `tests/v2-fix-probes.test.mjs` | ≈ 8.6 s | — | v2 的 flat 等权均值 / ≥2 名验证者 / runShell 失败分支（26 条） |
+| `tests/v2-path-escape.test.mjs` | ≈ 2.2 s | — | 验证日志路径逃逸（7 条） |
+| `tests/v2-tool-cap.test.mjs` | ≈ 0.4 s | — | 能力表来自真实组合、*MaxToolCalls 只是提示（10 条） |
 
 单套件耗时（并行时的关键路径按此排序）：
 
 | 套件 | 耗时 | 备注 |
 |---|---|---|
-| `e2e-v4-fixes.test.mjs` | **≈ 98 s** | 9 个用例是**轮次采样**型（如 T13 采样 400 轮、T19/T25 多轮）；时间 ≈ 轮数 × 框架自身的 40 ms 计时粒度 |
-| `formal-verify-v2.test.mjs` | **≈ 38 s** | 曾为 186 s：见 §3 |
+| `e2e-v4-fixes.test.mjs` | **≈ 104 s** | 9 个用例是**轮次采样**型（如 T13 采样 400 轮、T19/T25 多轮）；时间 ≈ 轮数 × 框架自身的 40 ms 计时粒度 |
+| `formal-verify-v2.test.mjs` | **≈ 43 s** | 曾为 186 s：见 §3 |
+| `e2e-v3.test.mjs` | ≈ 21 s | |
 | `e2e-regression.test.mjs` | ≈ 14 s | |
-| `e2e-business.test.mjs` | ≈ 13 s | |
-| `e2e-d9-d13.test.mjs` | ≈ 13 s | |
-| `e2e-v3.test.mjs` | ≈ 12 s | |
-| `formal-verify-v3.test.mjs` | ≈ 12 s | |
-| 其余 21 个 | ≤ 6 s | 其中绝大多数 < 1 s |
+| `formal-verify-v3.test.mjs` | ≈ 13 s | |
+| `e2e-business.test.mjs` / `e2e-d9-d13.test.mjs` | ≈ 13 s | |
+| 其余套件 | ≤ 10 s | 其中绝大多数 < 2 s |
+
+> 优化前：全量回归 ≈ 5.5 min（串行，`formal-verify-v2` 单独 186 s）；
+> 探针脚本 ≈ **38 min**（49 条串行，其中 12 条 × `formal-verify-v2` 162 s）。
+> 现在：**一套 `node tests/run-tests.mjs` ≈ 3.5 min 覆盖套件 + 探针**（探针单独跑仍是 ≈2.6 min）。
 
 ## 3. 已经做过的优化（别再重复踩）
 
@@ -68,9 +93,9 @@ node tests/audit-v5-integrity.mjs            # 静态：v5 完整性/理念门
    现在连续 100 次无待答 followup 就停（`V4_IDLE_POLLS` 可调）。
    **再往下压就要砍采样深度了**——那 9 个慢用例（T13/T19/T22/T23/T25/T27/T2/T9/T20）是在
    观察"多轮之后某个指令**没有**泄漏/重复"，轮数是它们的不变式本体，不要再动。
-3. **两个 runner 并行**（本轮新增）：探针 38 min → 2.6 min（sum 612 s，wall 154.6 s，x3.96）；
+3. **两个 runner 并行**（Round A）：探针 38 min → 2.6 min（sum 612 s，wall 154.6 s，x3.96）；
    全量回归 5.5 min → 1.9 min（sum 221.5 s，wall 111.5 s，x1.99）。
-4. **虚拟时钟**（`prompt-v5-integrity.test.mjs`，本轮新增）：v5 研究所由 `ctx.timeout` + `Date.now()`
+4. **虚拟时钟**（`prompt-v5-integrity.test.mjs`）：v5 研究所由 `ctx.timeout` + `Date.now()`
    驱动，真实时钟下"哪个成员被心跳/会议唤醒"取决于负载与毫秒差 → **随包语料每跑一次都变**（无法 diff，
    真实缺陷会被淹没）。套件现在把 `ctx.timeout` 接到**虚拟时钟**、`sleep(n)` 推进虚拟时间：
    套件 **7–9 s → 1.7 s**，且语料连续 6 次运行**字节一致**。语料写入端另加**全序排序**
@@ -79,13 +104,21 @@ node tests/audit-v5-integrity.mjs            # 静态：v5 完整性/理念门
    > 想给别的套件套用同一手法前请注意：若套件的等待助手用 `Date.now()` 做**超时判据**、又用
    > `setInterval` 轮询（例如 `e2e-v4-fixes.test.mjs` 的 `waitFor`），冻结时钟会让判据永不超时；
    > 那种情况必须连**轮询定时器**一起虚拟化，不能只改 `sleep`。
+5. **语料里的随机 id 也要归一化**（Round B，`formal-verify-v4.test.mjs`）：v4 的
+   `propose_task` 用 `Math.random` 造 `t-<8 位 hex>`，语料把 `[YOU CLAIMED TASK t-…]` 逐字写盘，
+   于是**每次跑测试都会改写随包语料**（`git status` 永远有 `prompt-corpus-v4/*`，且违反
+   `AUDIT-CHECKLIST` §2.4"连续两次哈希相同"）。`scrub()` 现在把它归一化成 `<TASKID>`，并断言
+   "语料里既没有裸 id、也真的有 `<TASKID>`"。连续两次运行哈希相同（`d3381886…` / `e6c4e445…`）。
 
 ## 4. 并行安全（为什么可以并发）
 
 - 每个套件/探针都自建 `mkdtempSync` 工作区，互不共享状态；
 - **会写语料的套件必须给不同的语料目录**：`V2_CORPUS_DIR` / `V3_CORPUS_DIR` / `V4_CORPUS_DIR` /
   `V5_CORPUS_DIR`。探针 runner 为**每个探针**分配独立目录，否则同一套件的并发实例会互相覆盖语料；
+- `audit-v5-sensitivity.mjs` 现在**自己**把 `V5_CORPUS_DIR` 指向临时目录：被变异的插件绝不能把
+  自己的提示词倒进随包语料；
 - `audit-persona-sensitivity.mjs` 用 `PERSONA_ROOT` 指向变异副本，且在覆盖模式下**不写**语料；
+- `audit-formal-sensitivity.mjs` 同样给每个探针独立的 `V{2,3,4,5}_CORPUS_DIR`；
 - `audit-prompt-invariants.mjs --self-probe` 用 `PROMPT_INVARIANTS_MUTATE`（JSON `[rel, from, to]`）
   在**内存里**变异一个文件并自我重跑，**不碰磁盘**，因此可与任何东西并发；
   变异串里不要用 NUL 分隔（环境变量不允许 NUL 字节）。
@@ -94,11 +127,11 @@ node tests/audit-v5-integrity.mjs            # 静态：v5 完整性/理念门
 
 | 目的 | 跑什么 | 预期 |
 |---|---|---|
-| 改了某个架构的插件 | `node tests/run-tests.mjs --only <vN>` + `node tests/audit-formal-sensitivity.mjs --only=vN` | 30 s – 2 min |
-| 改了提示词/人设 | `node tests/run-tests.mjs --only persona --only prompt` + `node tests/audit-persona-sensitivity.mjs` | ≈ 15 s |
-| **改了任何工具的参数 schema / 参数处理** | `node tests/audit-prompt-invariants.mjs --self-probe` + `node tests/run-tests.mjs --only formal` | ≈ 40 s（v2 套件占大头） |
-| 改了共享契约 / 发版前 | `node tests/run-tests.mjs` + `node tests/audit-formal-sensitivity.mjs` + `node tests/audit-persona-sensitivity.mjs` + `node tests/audit-prompt-invariants.mjs --self-probe` + `node tests/audit-spec-traceability.mjs` + `node tests/audit-v5-integrity.mjs` | ≈ 4.5 min |
-| 只想快速看提示词/文档有没有漂移 | `node tests/audit-prompt-invariants.mjs && node tests/audit-spec-traceability.mjs` | **< 0.5 s** |
+| 改了某个架构的插件 | `node tests/run-tests.mjs --only <vN>` + `node tests/audit-formal-sensitivity.mjs --only=vN` | 30 s – 3.5 min |
+| 改了提示词/人设 | `node tests/run-tests.mjs --only persona --only prompt` + `node tests/audit-persona-sensitivity.mjs` | ≈ 20 s |
+| **改了任何工具的参数 schema / 参数处理** | `node tests/run-tests.mjs --only audit-prompt-invariants --only formal` | ≈ 60 s（v2 套件占大头） |
+| 改了 `tests/` 下的 runner/守卫 | `node tests/run-tests.mjs`（**必须**：它现在同时跑套件与探针，任何一条守卫变红都会让门禁失败） | **≈ 3.5 min** |
+| 只想快速看提示词/文档有没有漂移 | `node tests/audit-prompt-invariants.mjs && node tests/audit-spec-traceability.mjs` | **< 3 s** |
 | 只想知道"快不快" | `node tests/run-tests.mjs --json` | 读 `wallSeconds` / `slowest` |
 
 **每次跑完都要看那几行 timing**：如果某个套件突然比基线慢很多，先怀疑新增的固定等待，

package/installer.js

@@ -27,10 +27,16 @@
 //         provides a real one (copy the preset: the picker's copy action, or a new directory
 //         under <presetRoot>), which leaves the managed set updatable.
 //   - Nothing is destroyed silently: before a file whose bytes are not what the installer last
-//     wrote is replaced, the user's copy is kept under
-//     <presetRoot>/.vibe-math-backup/<fromVersion>/<preset>/<file> and named in the log.
-//   - same version: no-op (idempotent) — restarting DSH never rewrites a file or churns the
-//     preset's generation stamp. Missing files are ALWAYS restored, at any version.
+//     wrote is REPLACED — or DELETED along with a preset this bundle no longer ships — the user's
+//     copy is kept under <presetRoot>/.vibe-math-backup/<fromVersion>/<preset>/<file> and named in
+//     the log. A file that still matches the hash recorded for it is a copy of the package, so
+//     removing it destroys nothing and needs no backup.
+//   - Files are written ATOMICALLY: a uniquely named temp file is written and then renamed over the
+//     destination, so an interrupted boot (a kill, a full disk, two sessions writing at once) can
+//     never leave a half-written preset for the next same-version run to mistake for a user edit.
+//   - same version: no-op (idempotent) — restarting DSH never rewrites a preset file, never churns
+//     the preset's generation stamp and never rewrites this state file (it is written only when its
+//     content actually changes). Missing files are ALWAYS restored, at any version.
 //   - force a full refresh at any time: delete the preset dirs and restart DSH.
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, unlinkSync, rmdirSync } from 'node:fs'
 import { createRequire } from 'node:module'
@@ -76,6 +82,27 @@ const BACKUP_DIR = '.vibe-math-backup'
 
 function sha256(buf) { return createHash('sha256').update(buf).digest('hex') }
 
+let presetTmpSeq = 0
+/**
+ * Write one preset file ATOMICALLY: a uniquely named temp sibling, then a rename over the
+ * destination. An in-place `writeFileSync` can be interrupted (a killed or crashed DSH, a full disk,
+ * two sessions writing the same path) and leave a TRUNCATED preset behind — and the next
+ * same-version boot would take those bytes for the user's own edit and never repair them (a
+ * same-version run only restores MISSING files). The pid plus a per-process sequence make the temp
+ * name unique, so concurrent writers cannot rename each other's half-written file. A leftover temp
+ * (possible only after SIGKILL between the two calls) is inert: DSH reads the named preset files.
+ */
+function writePresetFile(dest, buf) {
+  const tmp = dest + '.' + process.pid + '.' + (presetTmpSeq++) + '.vibe-math-tmp'
+  try {
+    writeFileSync(tmp, buf)
+    renameSync(tmp, dest)
+  } catch (e) {
+    try { unlinkSync(tmp) } catch (e2) { /* nothing of ours to clean up */ }
+    throw e
+  }
+}
+
 /**
  * Preserve one file that is about to be replaced by the shipped version, under
  * `<presetRoot>/.vibe-math-backup/<fromVersion>/<preset>/<file>`.
@@ -107,13 +134,57 @@ function readState(path) {
   return null
 }
 
-function writeState(path, state) {
+/**
+ * Does the new payload equal the recorded one? Compared field by field (never as JSON text) so key
+ * ORDER cannot fake a change, and the timestamp is ignored on purpose: `updatedAt` records when the
+ * file was written, not that anything happened.
+ */
+function sameStatePayload(previous, next) {
+  if (!previous || !next) return false
+  if (String(previous.version || '') !== String(next.version || '')) return false
+  const a = previous.files || {}
+  const b = next.files || {}
+  const ka = Object.keys(a).sort()
+  const kb = Object.keys(b).sort()
+  if (ka.length !== kb.length) return false
+  for (let i = 0; i < ka.length; i++) {
+    if (ka[i] !== kb[i]) return false
+    const ra = a[ka[i]] || {}
+    const rb = b[kb[i]] || {}
+    if (String(ra.hash || '') !== String(rb.hash || '')) return false
+    if (String(ra.provenance || '') !== String(rb.provenance || '')) return false
+  }
+  return true
+}
+
+let stateTmpSeq = 0
+let stateWriteWarned = false
+/**
+ * Persist the state file, atomically. Three things here are deliberate:
+ *   · an UNCHANGED payload is not written at all — a same-version boot must not churn this file (the
+ *     "restarting DSH writes nothing" promise covers the state file too, not only the presets);
+ *   · the temp name carries the pid and a sequence, so two concurrent boots cannot rename each
+ *     other's half-written file (with a fixed `path + '.tmp'` the loser's rename failed and the
+ *     whole write vanished without a word);
+ *   · a failure is REPORTED once instead of being swallowed. The copy step already did its work; a
+ *     missing state only means the next boot re-compares everything (at worst it backs up one extra
+ *     original, it never overwrites a user edit).
+ */
+function writeState(path, state, previous, logger) {
+  if (sameStatePayload(previous, state)) return 'unchanged'
+  const tmp = path + '.' + process.pid + '.' + (stateTmpSeq++) + '.tmp'
   try {
-    const tmp = path + '.tmp'
     writeFileSync(tmp, JSON.stringify(state, null, 2) + '\n', 'utf8')
     renameSync(tmp, path)
+    return 'written'
   } catch (e) {
-    // best-effort: state persistence failure must not break the copy step
+    try { unlinkSync(tmp) } catch (e2) { /* nothing of ours to clean up */ }
+    if (!stateWriteWarned) {
+      stateWriteWarned = true
+      logger?.warn?.('[dsh-vibe-math] 状态文件写入失败（' + path + '）：' + String((e && e.message) || e) +
+        '。preset 文件本身已按上面的日志处理完毕；下一次启动会按「没有记录」重新比对（最坏情况是多备份一份原文，不会覆盖你的改动）。')
+    }
+    return 'failed'
   }
 }
 
@@ -129,12 +200,30 @@ function writeState(path, state) {
 //      that works on a global <= 0.1.6 install.
 // When none resolves, the capability self-check below is still the authoritative gate.
 const __require = createRequire(import.meta.url)
+
+// The detected version is only ever used for diagnostics, and this probe sits on the installer ROW's
+// activation path: a service that never answers must not hold the boot there. On timeout (or on a
+// rejection) the next source is tried instead — no verdict depends on this value.
+const LIST_BUNDLES_TIMEOUT_MS = 1500
+function withTimeout(promise, ms) {
+  return new Promise((resolve) => {
+    let settled = false
+    let timer
+    const done = (value) => { if (!settled) { settled = true; clearTimeout(timer); resolve(value) } }
+    timer = setTimeout(() => { if (!settled) { settled = true; resolve(undefined) } }, ms)
+    if (timer && typeof timer.unref === 'function') timer.unref()
+    Promise.resolve(promise).then(done, () => done(undefined))
+  })
+}
+
 async function detectDshVersion(ctx) {
   try { const v = process.env.DSH_VERSION; if (v && String(v).trim()) return { version: String(v).trim(), source: 'DSH_VERSION' } } catch (e) {}
   try {
     const pm = (ctx && ctx.get) ? ctx.get('pluginManager') : undefined
     if (pm && typeof pm.listBundles === 'function') {
-      const bundles = await pm.listBundles()
+      // withTimeout: a slow or stuck pluginManager falls through to the next source instead of
+      // stalling this row's activation (non-fatal either way — see the constant's comment).
+      const bundles = await withTimeout(pm.listBundles(), LIST_BUNDLES_TIMEOUT_MS)
       const host = (bundles || []).find((b) => b && (b.name === '@deepseek-ai/dsh-base' || b.name === '@deepseek-ai/dsh'))
       if (host && host.version) return { version: String(host.version), source: 'pluginManager:' + host.name }
     }
@@ -161,12 +250,14 @@ async function detectDshVersion(ctx) {
  *   'directory' — DSH <= 0.1.6: <DSH_HOME>/.agent-presets/<id>/agent.cordis.yml, which is what the
  *                 copy in apply() installs.
  *
- * Judged from the LOADER TREE, not from the version and not from the `agentPresets` service: that
- * service exists on BOTH lines with different meaning (a directory scanner below 0.1.7, a row registry
- * from 0.1.7 on), and it may not be up yet when a bundle is activated on its own. Missing the row line
- * would skip the only working install path, so this decision has to be the reliable one.
+ * Judged from the LOADER TREE first, then from the one capability that actually differs between the
+ * two lines: the `agentPresets` service. That service exists on BOTH lines with different meaning (a
+ * directory scanner below 0.1.7, a row registry from 0.1.7 on) and may not be up yet when a bundle is
+ * activated on its own, which is why the tree is asked first — but when only the service can be seen,
+ * `register` (never `list`, which both have) is what tells them apart. Missing the row line would skip
+ * the only working install path, so this decision has to be the reliable one.
  */
-function detectPresetMechanism(ctx) {
+export function detectPresetMechanism(ctx) {
   // 1) the LOADER TREE: only the row-based line mounts the agent-preset package (or its registry).
   //    This is visible before any plugin activates, which matters because a bundle activation can run
   //    this installer before the services are up (then ctx.get('agentPresets') is still undefined).
@@ -180,11 +271,23 @@ function detectPresetMechanism(ctx) {
       }
     }
   } catch (e) { /* no loader service: fall through to the service probe */ }
-  // 2) the service itself (>= 0.1.7), when it is already available.
+  // 2) the service itself, when it is already available. The PRECISE capability difference between
+  //    the two lines is `register`: the >= 0.1.7 row registry has it, the <= 0.1.6 directory scanner
+  //    is INFERRED to lack it. The record is partial — a real 0.1.6-alpha.2 boot exposed the service
+  //    and its `list()` returned the directory roster (_oneoff/roster-016a2.json), but that probe
+  //    never ASKED for `register`; the inference follows from the package difference (npm:
+  //    0.1.6-alpha.2 ships no `@deepseek-ai/dsh-agent-preset`, while 0.1.7-rc.2 adds it). The
+  //    misclassification this guards against is therefore a LATENT RISK, not an observed failure:
+  //    testing `list` (which BOTH lines have) would classify a service-ready old host as the row
+  //    line, and apply() would then return before writing a single preset directory — "installed but
+  //    invisible", the 2.4.0 defect mirrored onto the older line. That outcome was never observed:
+  //    the recorded 0.1.6 boot DID write all four preset directories. Never test a capability both
+  //    lines share.
   try {
     const ap = (ctx && ctx.get) ? ctx.get('agentPresets') : undefined
-    return (ap !== undefined && typeof ap.list === 'function') ? 'rows' : 'directory'
-  } catch (e) { return 'directory' }
+    if (ap !== undefined) return typeof ap.register === 'function' ? 'rows' : 'directory'
+  } catch (e) { /* no service to ask: the directory form */ }
+  return 'directory'
 }
 
 /**
@@ -222,7 +325,8 @@ export function satisfiesDshRange(version, range, options = {}) {
       const admitted = parsed.some((p) => p.target !== null && p.target.pre.length > 0 &&
         p.target.major === v.major && p.target.minor === v.minor && p.target.patch === v.patch)
       if (!admitted) continue
-    }    if (parsed.every((p) => matchesComparator(v, p))) return true
+    }
+    if (parsed.every((p) => matchesComparator(v, p))) return true
   }
   return sawUnknown ? null : false
 }
@@ -478,7 +582,9 @@ export async function apply(ctx) {
 
     const nextFiles = {}
     let installed = 0, updated = 0, kept = 0
+    let userEditedKept = 0
     const replacedEdits = []
+    const unknownPrev = []
     const backupFailures = []
 
     for (const p of PRESETS) {
@@ -495,7 +601,7 @@ export async function apply(ctx) {
         const curHash = sha256(cur)
         if (!existsSync(d)) {
           // missing file: always restore, whatever the version
-          writeFileSync(d, cur)
+          writePresetFile(d, cur)
           installed += 1
           nextFiles[key] = { hash: curHash, provenance: 'package' }
           continue
@@ -514,17 +620,32 @@ export async function apply(ctx) {
           // same version: nothing is being updated, so a file that differs from the package is left
           // exactly as it is. The recorded hash stays "what this installer last wrote" (or unknown),
           // so the drift is still recognised — and backed up — at the next version change.
+          //
+          // PROVENANCE, recorded honestly: when the on-disk bytes are NOT what this installer last
+          // wrote, something else edited this managed file, so it is marked user-owned — which is
+          // what makes the stale-preset cleanup below KEEP it instead of unlinking it. A legacy
+          // state with no hash cannot tell, so it stays 'package' (it is still backed up before any
+          // version-change replacement; the cleanup backs it up before deleting too).
           kept += 1
-          nextFiles[key] = typeof prevRec.hash === 'string' ? { hash: prevRec.hash, provenance: 'package' } : { provenance: 'package' }
+          const userEdited = typeof prevRec.hash === 'string' && destHash !== prevRec.hash
+          if (userEdited) userEditedKept += 1
+          nextFiles[key] = userEdited
+            ? { hash: prevRec.hash, provenance: 'user' }
+            : typeof prevRec.hash === 'string' ? { hash: prevRec.hash, provenance: 'package' } : { provenance: 'package' }
           continue
         }
-        // replacing: preserve the user's bytes when they are not what this installer last wrote
-        // (a legacy state without a hash cannot tell, so it backs the file up rather than risk it)
-        if (typeof prevRec.hash !== 'string' || destHash !== prevRec.hash) {
+        // replacing: preserve the user's bytes when they are not what this installer last wrote.
+        // The two cases are NOT the same claim and are counted apart: bytes that differ from the
+        // recorded hash are a provable edit, while a legacy state WITHOUT a hash cannot tell — that
+        // file is backed up all the same, but the log must not call it "被改过" (it cannot know).
+        if (typeof prevRec.hash !== 'string') {
+          if (backupReplacedFile(presetRoot, fromVersion, p.dst, f, destBuf) === 'failed') backupFailures.push(key)
+          unknownPrev.push(key)
+        } else if (destHash !== prevRec.hash) {
           if (backupReplacedFile(presetRoot, fromVersion, p.dst, f, destBuf) === 'failed') backupFailures.push(key)
           replacedEdits.push(key)
         }
-        writeFileSync(d, cur)
+        writePresetFile(d, cur)
         updated += 1
         nextFiles[key] = { hash: curHash, provenance: 'package' }
       }
@@ -534,10 +655,21 @@ export async function apply(ctx) {
     // removed at v2.0.0). The copy loop only adds/updates PRESETS; it never deletes a preset that
     // was dropped, so an old removed preset would linger in the picker forever. Here we remove the
     // files this installer previously recorded as package-owned under a prefix that is no longer in
-    // PRESETS, then drop the dir if it became empty. User-owned files (provenance 'user') are kept.
+    // PRESETS, then drop the dir if it became empty. Files recorded as user-owned are KEPT.
+    //
+    // DELETION IS THE ONE PATH THAT DOES NOT REPLACE, so it obeys the same rule as the replacement
+    // path: a file whose bytes are not what this installer last wrote is copied to
+    // <presetRoot>/.vibe-math-backup/<fromVersion>/<preset>/<file> FIRST and named in the log. A file
+    // that still matches its recorded hash IS the package's copy, so removing it destroys nothing.
     const currentPrefixes = new Set(PRESETS.map(p => p.src + '/'))
     let removedFiles = 0
-    let removedDirs = []
+    let matchedPackageFiles = 0
+    let keptUserFiles = 0
+    const removedDirs = []
+    const backedUpStale = []
+    const backupFailedStale = []
+    const unreadableStale = []
+    const keptUserDirs = new Set()
     const stale = new Map() // prefix -> [keys]
     for (const key of Object.keys(prevFiles)) {
       const slash = key.indexOf('/')
@@ -551,47 +683,95 @@ export async function apply(ctx) {
       let dirEmpty = true
       for (const key of keys) {
         const rec = (prevFiles[key] && typeof prevFiles[key] === 'object') ? prevFiles[key] : { provenance: 'package' }
-        if (rec.provenance === 'user') { dirEmpty = false; continue }   // 用户文件 → 保留
+        if (rec.provenance === 'user') { dirEmpty = false; keptUserFiles += 1; keptUserDirs.add(prefix.slice(0, -1)); continue }   // 用户文件 → 保留
         const f = join(presetRoot, key)
-        if (existsSync(f)) { try { unlinkSync(f); removedFiles += 1 } catch (e) {} }
+        if (existsSync(f)) {
+          let buf = null
+          try { buf = readFileSync(f) } catch (e) { /* unreadable: treated as "cannot prove it is ours" */ }
+          // A file that still matches its recorded hash IS the copy this installer wrote, so deleting
+          // it destroys nothing. Anything else — edited bytes, or a legacy record with no hash that
+          // cannot tell — is copied to the backup root first. Deletion is allowed ONLY when nothing of
+          // the user's can be lost: a package copy, or bytes that really were preserved. An unreadable
+          // file cannot be backed up, and a FAILED backup means the bytes were not preserved either —
+          // both are KEPT and named in the log. A stale directory left behind is cosmetic; destroyed
+          // user bytes are not. (The REPLACEMENT path above keeps its own rule — a failed backup must
+          // not block a version upgrade — because there the file is overwritten, not removed.)
+          const isPackageCopy = buf !== null && typeof rec.hash === 'string' && sha256(buf) === rec.hash
+          let mayDelete = false
+          if (isPackageCopy) {
+            matchedPackageFiles += 1
+            mayDelete = true
+          } else if (buf !== null) {
+            const cut = key.lastIndexOf('/')
+            const backup = backupReplacedFile(presetRoot, fromVersion, key.slice(0, cut), key.slice(cut + 1), buf)
+            if (backup === 'failed') backupFailedStale.push(key)
+            else { backedUpStale.push(key); mayDelete = true }
+          } else {
+            unreadableStale.push(key)
+          }
+          if (mayDelete) { try { unlinkSync(f); removedFiles += 1 } catch (e) {} }
+        }
         if (existsSync(f)) dirEmpty = false
       }
       const dir = join(presetRoot, prefix.slice(0, -1))
       if (dirEmpty && existsSync(dir)) { try { rmdirSync(dir); removedDirs.push(dir) } catch (e) {} }
     }
 
-    writeState(stateFile, { version: pkgVersion || (state && state.version) || '', files: nextFiles, updatedAt: Date.now() })
+    writeState(stateFile, { version: pkgVersion || (state && state.version) || '', files: nextFiles, updatedAt: Date.now() }, state, logger)
 
-    if (removedFiles > 0 || removedDirs.length > 0) {
-      logger?.info?.('[dsh-vibe-math] preset cleanup: removed ' + removedFiles + ' file(s) from ' + removedDirs.length + ' stale preset dir(s) (' + removedDirs.map(d => d.split(/[\\/]/).pop()).join(', ') + ') that are no longer shipped.')
+    const cleanupNotes = []
+    if (matchedPackageFiles > 0) cleanupNotes.push(matchedPackageFiles + ' 个仍是本安装器写入的字节（删掉的不是你的改动）')
+    if (backedUpStale.length > 0) cleanupNotes.push(backedUpStale.length + ' 个的字节与上一次安装不同（被改过），原文已备份在 ' + join(presetRoot, BACKUP_DIR, String(fromVersion)) + '：' + backedUpStale.join(', '))
+    if (backupFailedStale.length > 0) cleanupNotes.push(backupFailedStale.length + ' 个被改过的文件**备份失败**（原文未保留，已跳过删除并保留原文件）：' + backupFailedStale.join(', '))
+    if (unreadableStale.length > 0) cleanupNotes.push(unreadableStale.length + ' 个文件**无法读取**（既不能证明是本安装器写入的，也无法备份），已跳过删除并保留原文件：' + unreadableStale.join(', '))
+    if (keptUserFiles > 0) cleanupNotes.push(keptUserFiles + ' 个记为用户所有的文件被保留（' + [...keptUserDirs].join(', ') + '），要清理请手动删除')
+    if (removedFiles > 0 || removedDirs.length > 0 || cleanupNotes.length > 0) {
+      logger?.info?.('[dsh-vibe-math] preset cleanup: removed ' + removedFiles + ' file(s) from ' + removedDirs.length + ' stale preset dir(s) (' + removedDirs.map(d => d.split(/[\\/]/).pop()).join(', ') + ') that are no longer shipped' +
+        (cleanupNotes.length > 0 ? '；' + cleanupNotes.join('；') : '') + '。')
     }
 
+    const backupsDir = join(presetRoot, BACKUP_DIR, String(fromVersion))
+    // Two kinds of preserved bytes, reported apart because they are not the same claim:
+    //   · replacedEdits — the bytes on disk are NOT what this installer last wrote: a provable edit.
+    //   · unknownPrev   — a legacy state with no hash cannot tell; backed up all the same, and never
+    //                     called "被改过" (the old wording claimed an edit it could not see).
+    const editClause = replacedEdits.length > 0
+      ? '其中 ' + replacedEdits.length + ' 个文件与上一次安装的字节不同（被改过），已按版本一致化覆盖' +
+        (backupFailures.length === 0
+          ? '，原文备份在 ' + backupsDir + '：' + replacedEdits.join(', ')
+          : '；这 ' + backupFailures.length + ' 个文件**备份失败**（原文未保留）：' + backupFailures.join(', ')) +
+        '。要自定义 preset，请复制一份而不是改这几个文件——被管理的文件在下一次版本变更时一定会被替换。'
+      : ''
+    const unknownClause = unknownPrev.length > 0
+      ? '另有 ' + unknownPrev.length + ' 个文件在旧版状态里没有哈希（无法判断你是否改过），已先备份原文到 ' + backupsDir + ' 再替换' +
+        (backupFailures.length > 0 ? '（其中备份失败：' + backupFailures.join(', ') + '）' : '') + '。'
+      : ''
+
     if (isUpgrade) {
       logger?.info?.('[dsh-vibe-math] preset auto-update: version ' + fromVersion + ' → ' + pkgVersion +
         ' — 新增 ' + installed + ' 个文件，更新 ' + updated + ' 个文件。' +
-        (replacedEdits.length > 0
-          ? '其中 ' + replacedEdits.length + ' 个文件与上一次安装的字节不同（被改过），已按版本一致化覆盖' +
-            (backupFailures.length === 0
-              ? '，原文备份在 ' + join(presetRoot, BACKUP_DIR, String(fromVersion)) + '：' + replacedEdits.join(', ')
-              : '；这 ' + backupFailures.length + ' 个文件**备份失败**（原文未保留）：' + backupFailures.join(', ')) +
-            '。要自定义 preset，请复制一份而不是改这几个文件——被管理的文件在下一次版本变更时一定会被替换。'
-          : '') +
+        editClause + unknownClause +
         '新版本 preset 将在新会话生效。')
     } else if (isBaseline) {
       logger?.info?.('[dsh-vibe-math] preset baseline: refreshed ' + (installed + updated) + ' file(s) to v' + pkgVersion +
         (replacedEdits.length > 0
           ? '，其中 ' + replacedEdits.length + ' 个原有文件与随包版本不同' +
-            (backupFailures.length === 0 ? '，原文已备份在 ' + join(presetRoot, BACKUP_DIR, String(fromVersion))
+            (backupFailures.length === 0 ? '，原文已备份在 ' + backupsDir
               : '，但有 ' + backupFailures.length + ' 个备份失败（原文未保留）：' + backupFailures.join(', '))
           : '') +
+        unknownClause +
         ' — 已启用版本化自动更新（后续版本变更会直接替换被管理的 preset 文件）。')
-    } else if (installed > 0) {
-      logger?.info?.('[dsh-vibe-math] restored ' + installed + ' missing preset file(s)')
-    } else if (kept > 0) {
-      // same version, and some managed file on disk differs from the package: reported, never
-      // rewritten mid-version (it is replaced, with a backup, at the next version change)
-      logger?.info?.('[dsh-vibe-math] preset files untouched (v' + pkgVersion + ' unchanged): ' + kept +
-        ' file(s) differ from the shipped copy; they will be replaced on the next version change (原件会先备份)')
+    } else if (installed > 0 || kept > 0) {
+      // SAME VERSION, and BOTH facts are reported: a missing file being restored must not hide the
+      // drift notice (the audit's repro: the log said "restored 1" and never mentioned the drift).
+      const parts = []
+      if (installed > 0) parts.push('restored ' + installed + ' missing preset file(s)')
+      if (kept > 0) {
+        parts.push(kept + ' file(s) differ from the shipped copy and were left untouched (v' + pkgVersion + ' 未变)' +
+          (userEditedKept > 0 ? '，其中 ' + userEditedKept + ' 个是安装之后的改动（记为用户所有：弃用 preset 的清理不会删除它们）' : '') +
+          '；下一次版本变更会先备份原文再替换')
+      }
+      logger?.info?.('[dsh-vibe-math] preset files: ' + parts.join('；') + '。')
     }
     /* the host self-check ran at the top of apply() — it also decides the preset mechanism */
   } catch (err) {