pi-multi-viewers 0.5.0 → 0.5.1

package/AGENTS.md

@@ -21,15 +21,18 @@ fake_agent.py        测试薄壳：responder = 随机决策
 start_discussion.py  组合层：CLI 分发 + 环境创建/启动/清理（_resolve_spec / setup_environment）
 spec_gen.py          spec 生成层（question/骨架/viewers 校验与快照/agent 定义 + pi 环境探测）
 observability.py     观测层（check_status / --report / --wait / loop 存活检测）
+                     ↑ 分析目录内含 4 个模块的**运行快照**（非事实源）：改主仓代码
+                       对已启动的分析不生效，排查时用同名文件 diff 溯源
 human_viewer.py      【human 通道】只读展示（增量/--follow/游标）
 human_sayer.py       【human 通道】插话命令（单次/stdin/交互 -i）
 scripts/mv.sh        稳定入口 shim（exec mv_cli.py；路径被 prompt/README 引用）
 scripts/pi-probe.sh  LLM 探针（跑 pi + 登记新 session → 残留检查器可追溯）
+scripts/check-residue.sh  残留检查（session/进程/目录三类；增删 scripts/ 时同步本节）
 mv_cli.py            命令行实现（prepare/start/status/report/wait/cleanup/view/say）
 prompts/multi-viewers.md  /multi-viewers 入口（视角设计三原则 + 审核闸门）
 extensions/multi-viewers-say/  /multi-viewers-say 插话（registerCommand，零 LLM）
 docs/design.md       设计文档（fork 源模式与规模口径 + 决策记录）
-package.json         npm 包 pi-multi-viewers（pi.prompts 注册；发版待办）
+package.json         npm 包 pi-multi-viewers（pi.prompts 注册；**版本号唯一事实源**）
 templates/           AGENTS.md.tpl / agent.md.tpl / gitignore.tpl / spec-readme.md.tpl
 viewers/             示例视角（效率/简单/铁律——仅是形态示例，视角内容由用户按需自定）
 docs/examples/first-experiment/  首次实验存档（机制验证 + 模板原型 + 真实消息）
@@ -66,9 +69,11 @@ tests/               测试（unittest discover tests）
 为什么**不能**用插件全档（`all`）：两类插件在**我们这种 session 形态**上都是分钟级负担、
 且都在关键路径上（loop 等进程退出才继续）——
 · **AFT**：大 session 上进程退出前多活数分钟（受控对照 445.9s → 0.5s）；
-· **MC 全档**：它的 historian 对"带大段未处理历史"的 session **每次必失败并立刻重试**
-（受控对照：同输入 **447s → 10.3s，43 倍**）。
-零扩展**真场实测**：墙钟 12m31s / 每次唤醒 48.1s / 收尾≈0% / historian 0 次。
+· **MC 全档**：它的 historian 对"带大段未处理历史"的 session **在默认输出上限
+（32000）下**每次必失败并立刻重试（受控对照：同输入 **447s → 10.3s，43 倍**；根因 =
+推理流吃光输出上限——该上限**可调**：主 pi 抬到 131072 后首跑即成功、输出 36954 ✓）。
+零扩展**真场实测**：每次唤醒约 48–82s、收尾≈0%、historian 0 次（墙钟随唤醒数变动，
+区间与测点见 docs/design.md §二）。
 **mc-tools 档的实测**：entry **只注册工具、不装 hook** → historian 0/6 ✓（生产 0/3 ✓）；
 `ctx_search` 实测可用 ✓；成本**未测得显著差异**（受控探针 n 小、组内方差>组间差 ✗；
 生产基线：本场 strict=1、n=19，唤醒启动段中位 **0.68s**、收尾中位 0.04s ✓）。
@@ -198,6 +203,21 @@ loop、状态从 git 共享事实推导、单一事实源 = protocol.json、无
 `docs/test-methodology.md`——新方法在那里追加，AGENTS.md 不逐条同步
 （避免 100 个方法全堆进来）。
 
+## 文档维护纪律（2026-09-14 文档漂移自审共识）
+
+**文档不做第二事实源**——同一事实被多处抄写，抄本必随实现演进漂移（本轮实测：
+"目录发现兜底"一处行为被抄 3 份、全部滞后于代码；版本号 2 处、状态列举 3 版不一）。
+
+1. **有唯一事实源 → 一律引用，不复制**（与变更频率无关）：版本号 → `package.json`；
+   命令行选项 → `--help`；报告字段 → `docs/design.md`「观测面契约」；状态取值 →
+   `observability.check_status` 定义处；容量/规模 → `docs/design.md §二`。
+   **无事实源 → 补一行 + 增删同步**（按变更频率分级，如 `scripts/` 清单）。
+2. **复述类问题的改法优先级**：**删复述引权威** > **最短准确陈述**（无权威入口的
+   行为描述）> **就地改准确**（必须保留语境时）。
+3. **两条判据**：① 重复"计算"在冷路径可接受、重复"**事实**"在文档不可接受
+   （报告的两次遍历不合并；文档的复述必去）② **数字必须带口径**（测点/样本/是否
+   `--force`；单点数字不宜当承诺）。
+
 ## Git 准则（用户约定，沿用）
 
 1. **每次改动先更新本地 git**：对本项目代码/文档的每次修改，先 `git add` + `git commit` 记录。
@@ -211,9 +231,9 @@ loop、状态从 git 共享事实推导、单一事实源 = protocol.json、无
 
 - **当前形态**：prompt × 1（multi-viewers，开发机已注册可用）+
   extension × 1（multi-viewers-say 插话：零 LLM，直接 spawn human_sayer.py；
-  目录发现 = `<cwd>/mv-<sessionId>-*` 最新，兜底 `mv-*`（排除
-  `mv-spec-*`）并警告）
-  + wrapper。**npm 已发布 0.3.0（2026-09-12）**。
+  目录发现 = `<cwd>/mv-<sessionId>-*` 最新——**无兜底**：未匹配即报错
+  rc 1，需显式传目录）
+  + wrapper。**npm 已发布**（版本以 `package.json` / registry 为准）。
 - **开发机安装（两步，缺一不可；2026-09-10 实测）**：
   ① `pi install /root/pi-multi-viewers`——**注册包**（写
   `~/.pi/agent/settings.json` 的 `packages` 数组）；pi 不是"扫 node_modules

package/README.md

@@ -33,7 +33,8 @@
 2026-09-10；随主会话增长漂移），加模型 384k completion 预留即超 1M 窗口，
 provider 直接 400 拒绝（`pi --fork` 原生命令同样超窗）。budget 把基线压到
 ~80k est，首唤（唤醒 1 首请求）≈132k tokens，可正常进行（e2e 实测：
-三视角 15–19 分钟完整收敛）。权威口径与测点见 docs/design.md §二。
+三视角约 12–35 分钟完整收敛——决定因素是**扩展策略与唤醒数**，区间与测点见
+docs/design.md §二）。
 
 ## 安装
 
@@ -75,8 +76,9 @@ ls ~/.pi/agent/npm/node_modules/pi-multi-viewers/scripts/mv.sh
 执行"，不需要经过 LLM）。
 
 **目录可以省略**：`--view`/`--say`/`--status`/`--report`/`--wait`/`--cleanup`
-不带目录时自动定位"本 session 当前分析"（`mv-<sessionId>-*` 最新；找不到
-则取最新 `mv-*` 并警告；判据 = 含 `repo.git`）。传目录仍支持（显式优先）。
+不带目录时自动定位"本 session 当前分析"（只匹配 `mv-<sessionId>-*` 最新；**未匹配
+即报错退出、不猜目录**——破坏性命令尤其不能猜；判据 = 含 `repo.git`）。传目录仍支持
+（显式优先）。
 这样路径不需要经过任何 LLM 记忆——此前命令都要求绝对路径，等于让主 pi
 把长路径记在上下文里复用。
 
@@ -91,17 +93,19 @@ ls viewers/
 scripts/mv.sh --prepare "<主题>"              # spec = question.md(+background.md)
 scripts/mv.sh --start <spec目录>              # 启动（自动挂载主 session；默认 budget 模式）
 #  可选：--fork-mode compaction|budget|full（见上表；一般不调）
+#  可选：--extension-policy mc-tools|none|all（默认 mc-tools = agents 带 MC 的只读检索工具
+#        ctx_search；none = 零扩展、零依赖；all = 走 pi 默认发现。缺 MC 时 mc-tools 可见降级）
 #  高级：--agents "a,b" 起一次性视角（不建 viewers/ 时用；prompt 入口不传它）
 
 # 观看：--start 会输出可直接执行的 !! 流式观看命令（复制执行）
 scripts/mv.sh --view                          # 一次性增量查看（主 pi 记录 HEAD 作下轮 --since）
 #  --follow 会打印【状态】(meeting/all-freezing/round-robin/concluded)
 #         与【进度】(meeting 消耗/上限 ｜ freezing 集合 ｜ rr → 下一位)
-#         结束时自动附【分析报告】（消息/墙钟/配额/进程跨度/LLM 用量）
+#         结束时自动附【分析报告】（字段集以 docs/design.md「观测面契约」为准）
 
 # 插话 / 状态 / 收尾（目录可省略——自动定位本 session 当前分析）
 scripts/mv.sh --say "<文本>"                   # 插话（命令行形态；pi 内用 /multi-viewers-say）
-scripts/mv.sh --status                        # running / done / stalled / stopped（done 时附 [result] 路径）
+scripts/mv.sh --status                        # 状态 + 路径（取值与含义以该命令输出为准）
 scripts/mv.sh --report                        # 只读报告（流程/配额/进程/LLM/档位对照；冷路径，不持久化）
 scripts/mv.sh --cleanup                       # 收尾（result.md 自动留存到 <dir>-result.md）
 ```
@@ -159,7 +163,7 @@ human_viewer/sayer  human 插话通道
 ## 开发
 
 ```bash
-./tests/run_tests.sh          # 全量（~280s）
+./tests/run_tests.sh          # 全量（`--force` 语义，本机 ~300s；指纹未变时 --reuse 毫秒级）
 ./tests/run_tests.sh --reuse  # 指纹未变跳过
 ```
 

package/docs/design.md

@@ -102,7 +102,8 @@ compaction 的 `firstKeptEntryId` 起 + 其后的条目"——窗口内含 compa
 | `result.md`（固定位） | resultWriter loop | 结论文档 | 人 | 是（收尾判据） | — |
 | `--report`（视图） | observability | 文本行 | 人（**三个出口**，见下） | **否**（不得升级为验收 gate） | 冷路径一次性 —— **O(session 大小)**：每 agent 读整个 fork-src jsonl（实测 3 × 789KB ≈ 2.4MB/次、50–150ms/次，×3 出口 <0.3s/次分析），**不得进入任何轮询路径**（e2e16 评审量化） |
 
-**报告的字段集**（e2e17 评审后定稿）——**四组谓词分组 + 一组对照**，
+**报告的字段集**（e2e17 评审后定稿，后续增补不计数——字段行以本表为准）——
+**谓词分组 + 对照 + 事实行**，
 全部**只读已有家**（session 的文档化字段 + loop log 登记字段），不新增度量、
 不在 loop log 增记（同一事实两处 = 双写）：
 
@@ -270,9 +271,8 @@ commit 是溯源记录、本节是长期引用点——不并存两份权威值
    结果经 `ctx.ui.notify` 反馈——**不经过 LLM**（插话本质是本地命令执行；
    经 LLM 会引入不确定性与额外延迟）。目录发现零状态文件：
    `ctx.cwd` + `sessionManager.getSessionId()` → `mv-<sid>-*` 最新
-   （session 隔离）；无 sid 目录时兜底项目下最新 `mv-*`（排除
-   `mv-spec-*`）并**警告降级**
-   （宁可提示也不静默插错分析）。观看仍用 `!!` 流式（命令 API 无原生流式
+   （session 隔离）；**无兜底**——未匹配即报错 rc 1（行为事实源 = 决策 15：
+   破坏性命令不猜目录）。观看仍用 `!!` 流式（命令 API 无原生流式
    通道，bash 流式是平台原生能力）。
 10. **question.md 的主题行措辞 = `# 分析主题：`（唯一）**：生成端
     （`gen_question` / `gen_spec_skeleton`）、模板（`spec-readme`）、prompt、
@@ -280,6 +280,17 @@ commit 是溯源记录、本节是长期引用点——不并存两份权威值
     消费端**只认它**，旧措辞 spec → fail-fast（明确报错，不静默退化）。
     曾出现双轨（生成产 `# 讨论主题：`、消费端写兼容循环兜两种）——那
     正是"补丁掩盖设计缺陷"的形态（不改生产、只兜消费端）。
+10b. **无产出重试上限 3 + stall 兜底 600s**（机制事实，2026-09-14 补记）：
+    `meeting_engine.MAX_RETRY = 3` —— agent 唤醒后未产出消息时最多重试 3 次，每次重试
+    相当于**一次完整唤醒**（真场 48–87s/唤）→ 单轮最坏 **+2.5–4.5 分钟**；仍无产出则
+    loop 代写（不耗该 agent 配额）。`meeting_fs.DEFAULT_STALL_TIMEOUT = 600` —— 全体
+    无新 commit 达 600s 即进入"接管"分支（死锁的墙钟下限 = 10 分钟/次）。
+10c. **分析目录内的代码副本 = 运行快照（非事实源）**（机制事实，2026-09-14 补记）：
+    `start_discussion.setup_environment` 把 4 个模块拷进分析目录，`meeting_loop`
+    **从副本运行**（`start_discussion.py:416-419` / `:710`）。因此"改主仓代码对
+    正在跑的分析不生效"是**设计如此**；排查时可用副本与主仓同名文件 `diff` 溯源，
+    cleanup 后副本随目录消失、不可再追。
+
 11. **stall 接管 = 心跳式软仲裁（非互斥）**：非 rw 在无进展超时时接管收尾，
     先 pull 重检共享事实（concluded / result.md）→ 写接管声明 commit
     （**只为推进 HEAD**，使对方 `_stall_elapsed` 归零而退出该分支）→
@@ -393,7 +404,10 @@ commit 是溯源记录、本节是长期引用点——不并存两份权威值
     - 现状只关**语义搜索**，AFT 仍加载（trigram 索引、LSP、工具集、每 agent
       一个 `aft` 索引服务）。剩余实测成本：无扩展 2.2s / 仅 MC 2.8s /
       AFT（语义关）3.3–4.5s → **~1–2s/唤醒 ≈ 2% 墙钟**（33 唤醒 ≈ 1 分钟
-      / 55 分钟）。最初那 57s 已经拿回，**速度上几乎无剩余收益**。
+      / 55 分钟）。最初那 57s 已经拿回，**小 session 上几乎无剩余收益**。
+      **限定（2026-09-14 注记）**："2%" 仅来自**小 session 单点探针**、**不可外推**——
+      生产规模下 AFT 的收尾成本可达数分钟（见本节后文 445.9s 对照）；"是否屏蔽 AFT"
+      以决策 20（默认 mc-tools / none）为准，本句仅存档。
     - 三种屏蔽方式：`--no-extensions` + `-e <MC 扩展入口>`（AFT 不加载、
       MC 保留；入口可从 `~/.pi/agent/settings.json` 的 `packages` + 包的
       `pi.extensions` 解析，不硬编码）；`--pure`（全关，已实现）；现状。
@@ -461,7 +475,12 @@ commit 是溯源记录、本节是长期引用点——不并存两份权威值
       fork 自大历史）**每次必失败并立刻重试**——同一份 fork 源、同一极小任务受控
       对照：**给 MC 447.2s（其中 435.5s 是 3 次连续失败的 historian、尾部占 97%）
       vs 不给 MC 10.3s（43 倍）**。曾疑为 historian 模型 id 过期（已修，实测**仍然**
-      失败）→ 结论：对本项目的 session 形态，MC 的压缩机制**结构性不工作**。
+      失败）→ **修正（2026-09-14）**：根因至少含**可调默认上限**——MC 源码
+      `maxOutputTokens: historian?.maxTokens ?? 32000`，而 historian 模型是
+      reasoning:true（推理流吃光上限 → "all reasoning, no text"）。主 pi 把
+      `historian.maxTokens` 抬到 131072 后**首跑即成功**（其 context.db #916：
+      completed、输出 36954 > 旧上限 32000）。故原结论应限定为"**在该默认上限
+      （32000）下不工作**"；agents 会话（fork 大历史）在抬高上限后**未复测**。
     - **真场验证（零扩展）**：墙钟 **12m31s** / 32 次唤醒 / **每次唤醒 48.1s** /
       **收尾 ≈0%**（对照插件在场时 66–78%）/ **historian 0 次** / 并行度 2.42/3.0 /
       档位对照 ✓。同一机制的对照：e2e19 71.6s·17m19s、e2e20 81.6s·20m34s、
@@ -527,7 +546,7 @@ commit 是溯源记录、本节是长期引用点——不并存两份权威值
     将来若要为 agents 加回任何扩展，须**显式 opt-in + 净收益账**（本次实证：
     AFT/MC 两次都是"加了才知道贵"）。
 
-21. **git 守卫范围 = 从讨论 workdir 发起的操作**21. **git 守卫范围 = 从讨论 workdir 发起的操作**（`GIT_CEILING_DIRECTORIES`
+21. **git 守卫范围 = 从讨论 workdir 发起的操作**（`GIT_CEILING_DIRECTORIES`
    注入于 spawn）；主项目仓库不在守卫范围（agent 的 cwd 就是主项目，其
    约束归指令层 + 主项目 `.gitignore`）。要拦主仓库需换机制类（沙箱/钩子），
    经评估收益不支撑扩面。
@@ -577,6 +596,10 @@ commit 是溯源记录、本节是长期引用点——不并存两份权威值
 
 ---
 
+- **README 计时样本里的离群值 2494s**（2026-09-11，≈8× 中位）：成因未查（疑机器
+  负载/挂起）。**观测点**：`tests/.cache/last.log` 的 `Ran N tests in Ns` 序列
+  —— 若再次出现 >1000s 的单次值，比对同批 `--force` 的 CPU 时间以区分负载与挂起。
+
 ## 五、已知边界与未覆盖
 
 - `compaction` / `full` 两模式在长会话下的实跑行为未验证（分析中仅用

package/docs/reviews/2026-09-14-e2e25-doc-drift-review.md

@@ -0,0 +1,188 @@
+<!-- 存档：docs/reviews/2026-09-14-e2e25-doc-drift-review.md
+     来源：一次真实多视角分析的 result.md 原文（未删改，仅加本头与下方说明）。
+     分析场次目录已随 --cleanup 删除；文中消息编号（如 `效率/0003`）不可再核验，
+     仅作溯源线索（与代码注释引用约定一致：行为以自描述为准）。 -->
+
+# 存档说明
+
+- **主题**：审阅本项目「文档 vs 代码」的一致性（文档漂移）——找出确认为错的表述、
+  缺失项、文档间矛盾
+- **场次**：`mv-mv-main-20260914-133016`（3 视角：效率 / 简单 / 铁律；真实 pi 讨论，
+  以 `MV_MC_TOOLS_STRICT=1` + 默认档 `mc-tools` 启动）
+- **本场同时是"自然使用"观察**（任务书**完全没提工具**）：
+  - 工具调用合计：`bash 114 / read 46 / write 34`，**`ctx_search` 0 次**
+    （对照 e2e24：9 次——但那 9 次全由我写在任务书里的提问诱导，不构成需求证据）
+  - **historian 子进程 0 次**（mc-tools 档不装 hook，符合设计）
+  - 报告新段首吃真实数据：`扩展策略：声明 mc-tools ｜ 生效 mc-tools（strict=1）`、
+    `终止：共识（RR 全体 pass）`、唤醒构成表（34 唤 / rc≠0 0 次）
+- **核心结论（本场最有价值的一条）**：文档漂移的**根源不是文档不够多，而是"对实现的
+  复述"**——同一事实被多处抄写，抄本必随实现演进漂移。治本方向 = 现状描述**引事实源，
+  不复制**。
+- **抓到的最重一条（行为语义与实现相反，已复核）**：`README.md` / `AGENTS.md` /
+  `docs/design.md` **三处**仍写"目录发现找不到时兜底 `mv-*` 并警告"，而代码
+  （`observability.find_current_dir`，e2e16 评审 2:0:1 裁定删除兜底）是**无兜底、
+  未匹配即报错 rc 1**——读者会等一个永不到来的警告。
+- **其余**：`README.md` 缺 `--extension-policy` 说明；报告字段列表停留在旧版；
+  4 条缺失项（分析目录代码副本快照语义 / 无产出重试 / stall 600s 兜底 /
+  `check-residue.sh` 清单漏项）；3 条治理规则；5 条"明确不做"；2 条"待核"。
+- **落地**：`ba204ef`（#1 校准批 + #2 结论限定 + #3 治理与小修；含新增
+  AGENTS.md「文档维护纪律」节）· 446 测试全绿。
+
+---
+
+# 文档一致性审阅 · 三方共识结果
+
+**主题**：审阅 `pi-multi-viewers` 的「文档 vs 代码」一致性（文档漂移）：列出确认为错的
+表述与缺失项。
+**参与者**：效率 / 简单 / 铁律（3 视角；全流程 meeting 讨论 + round-robin 全员 pass）。
+**方法**：只读核对（每项带 `文件:行`，锚点经两方以上逐行复核）；审阅对象 = 主仓库
+工作区现场原文。**本场未修改任何文件**。
+
+---
+
+## 0. 结论摘要
+
+1. **文档漂移的根源不是"文档不够多"，而是"对实现的复述"**——同一事实被多处抄写，
+   抄本必随实现演进漂移（本场找到：行为描述 3 处副本、状态列举 3 版不一、版本状态 2 处、
+   数字/容量多处）。治本方向 = **现状描述引事实源，不复制**。
+2. **最重的一条是唯一一类"行为语义与实现相反"**：README / AGENTS / design.md 三处都
+   仍写着"目录发现找不到时**兜底 `mv-*` 并警告**"，而代码是**无兜底、未匹配即报错**
+   （读者会等一个永不到来的警告/误以为写入已降级）。
+3. **三条治理规则**（本场共识，见 §二）落地后，同类漂移结构性减少。
+4. 全部问题分三档：**#1 现状描述校准批** → **#2 E1（错误结论限定）** →
+   **#3 治理与小修**（见 §一）。三项"不做"与两项"待核"见 §五/§六。
+
+---
+
+## 一、确认问题清单（按优先级）
+
+### #1 现状描述校准批（引事实源 / 改准确 / 删复述）
+
+**① 行为语义反 · 三处副本（T1/T2）**
+
+| 位置 | 现象 | 代码依据 |
+|---|---|---|
+| `README.md:77-79` | "不带目录时自动定位…（`mv-<sessionId>-*` 最新；**找不到则取最新 `mv-*` 并警告**…）" | `observability.py:68-80`（docstring："**为什么没有**'取项目下最新 `mv-*`'的兜底（e2e16 评审 2:0:1 裁定删除）"）· `:90-91`（无 sid/无候选 → `None`，无兜底路径）· `:831-833`（失败文案"请显式传目录参数"+ rc≠0） |
+| `AGENTS.md:213-215` | "目录发现 = `<cwd>/mv-<sessionId>-*` 最新，**兜底 `mv-*`（排除 `mv-spec-*`）并警告**" | 同上 |
+| `docs/design.md:273-274`（决策 9 段） | "无 sid 目录时兜底项目下最新 `mv-*`…并**警告降级**" | 同上；且与**同文档决策 15**（`:315` 起，"**无降级兜底**"在 `:319-321`）直接矛盾 |
+
+**改法（两类，不可互换）**：
+- `README.md` / `AGENTS.md`（行为描述，`--help` 无此入口）→ **最短准确陈述**：
+  "只匹配本 session；未匹配则报错（rc 1），需显式传目录"。
+- `docs/design.md:273-274` → **删复述 + 引权威**：保留"目录发现零状态文件：
+  `ctx.cwd` + `sessionManager.getSessionId()` → `mv-<sid>-* 最新`（session 隔离）"
+  半句与"不静默"意图，删"兜底 `mv-*` 并警告降级"行为细节，行为引决策 15（`:315`）。
+
+**② 枚举缺失（E6/S1、S2）**
+
+| 位置 | 现象 | 改法 |
+|---|---|---|
+| `README.md` 命令区（约 `:91-107`） | 复述了 `--fork-mode` 等，却**缺 `--extension-policy none\|mc-tools\|all`**（`mv_cli.py` USAGE 实有；默认档 mc-tools）——该开关即"48.1s/唤醒 ↔ ~330s/唤醒"的档位 | 删枚举 → 引 `mv.sh --help` |
+| `README.md:100` + `prompts/multi-viewers.md`（第 4 步"结束回合"） | 报告字段列举停留在旧版（"消息/墙钟/配额/进程跨度/LLM 用量"）——新增的**唤醒构成 / 终止原因 / 扩展策略（声明 vs 生效）**零提及 | 删枚举 → 引 `docs/design.md §观测面契约`（`:79` 起；字段表 `:105`） |
+
+**③ 状态/计数复述（T5 / T3 / T6）**
+
+| 位置 | 现象 | 依据 / 改法 |
+|---|---|---|
+| `README.md:104` + `prompts/multi-viewers.md:89`（T5） | 状态列举三版不一：代码 **5 态**（running/done/stalled/stopped/not-exists）、README **4 态**（缺 not-exists）、prompt **3 态**（缺 stalled、not-exists） | 代码：`observability.py:103-106/151/171`（各有对外文案；`stalled` 是 `--wait` 退出后给动作的终态）。改法：**不枚举** → 引 `--status` 输出 / `check_status` 定义处 |
+| `AGENTS.md:32` + `:216`（T3） | 同段内自相矛盾（"发版**待办**" vs "已发布 **0.3.0**"），实际 `package.json:3` = **0.5.0**（tag v0.4.0/v0.5.0 在） | 改法：引 `package.json` / registry，不抄版本号 |
+| `docs/design.md:105`（T6） | 标题"报告的字段集…**四组谓词分组 + 一组对照**" vs 表格实际 **8 行**（后三行 扩展策略/终止/唤醒构成为新增） | 改法：标题**去计数**（"谓词分组 + 对照 + 事实行"） |
+
+### #2 E1（错误结论 · 证据范围 < 主张范围）
+
+- **位置**：`AGENTS.md:69-70`（活文档句）与 `docs/design.md` 决策 20（结论句
+  `:464`："对本项目的 session 形态，MC 的压缩机制**结构性不工作**"）。
+- **新证据（2026-09-14）**：该失败类根因至少含**可调默认上限**——MC 源码
+  `maxOutputTokens: historian?.maxTokens ?? 32000`；主 pi 把 `historian.maxTokens`
+  抬到 131072 后，historian 首跑即成功（MC 自己的 `context.db` #916：completed、
+  输出 **36,954** > 旧上限 32,000）。
+- **限度**：agents 会话（fork 大历史）在抬高上限后**未复测** → **"结构性"依据不足**。
+- **改法**：活文档直接改错句（限定为"**在该默认上限（32000）下不工作**"）；
+  决策段加**一行**作废/限定注记（日期 + 证据指针），不叠注记层。
+
+### #3 治理与小修
+
+| 项 | 位置 | 现象 / 改法 |
+|---|---|---|
+| **E2 + E7** | `AGENTS.md:68-74` ↔ `design.md` 决策 20；`README.md:36` / `design.md:51-52` | 数字/容量多处抄本（装置注记、容量"15–19 分钟"已被 e2e19–24 超出：12m31s / 17m19s / 20m34s / 14.2 分钟(853s) / 离群 1h13m）。改法：**单一源在 design.md**，AGENTS/README 只留"区间 + 决定因素（扩展策略/唤醒数）+ 指针"；数字带口径（首末 commit vs 全程、样本数、`--force`） |
+| **E3** | `docs/design.md:395-396`（AFT"~2% 墙钟""几乎无剩余收益"）↔ 同文档 `:459`（同插件大 session 收尾 **445.9s**，对照 0.5s） | 同一文档两处 ~100× 相反结论并存。改法：`:395-396` 加**一行限定注记**——"2% 仅小 session 单点探针、不可外推；重估'屏蔽 AFT'以决策 20 为准"（带日期 + 证据指针） |
+| **E4** | `meeting_engine.py:51` `MAX_RETRY = 3`（`respond_with_fallback`，`:313-345`） | 机制未文档化。改法：design.md 协议机制节一行式——"无产出重试上限 3 → 每次重试 ≈ 一次完整唤醒（真场 48–87s/唤）→ 单轮最坏 +2.5–4.5 分钟；仍无产出 loop 代写、不耗配额" |
+| **E5** | `meeting_fs.py:52` `DEFAULT_STALL_TIMEOUT = 600` | 未文档化。改法：一行式——"无进展兜底 600s → 死锁墙钟下限 10 分钟/次；任一 agent 可接管（心跳式软仲裁，非互斥）" |
+| **M1** | `start_discussion.py:416-419`（拷贝 4 模块）· `:710`（从副本运行） | **分析目录代码副本机制**零文档：它是运行快照（**非事实源**）、在跑期间可与主仓同名文件 `diff` 溯源、cleanup 后不可追。改法：AGENTS 架构节 + design.md 各一句 |
+| **S3 ≡ M3** | `AGENTS.md:26-27` | scripts 清单漏 `scripts/check-residue.sh`。改法：补一行 + "增删同步本节"（低 churn 事实，不结构改造） |
+| **T4** | `docs/design.md:530`（决策 21 标题**重复两遍**）· `observability.py:121-124`（"读路径统一走 fs.run_git…"注释**连续重复两行**） | 复制/合并事故；全文扫描（相邻重复行 + 行内重复）确认**仅此两处**（`meeting_loop.py:79-80` 的 `return 99999` 为 except 分支 + 兜底，非事故） |
+| **README:162** | `README.md:162` "全量（~280s）" | 零成本取证（主会话时间戳，14 样本 282–331s、中位 ≈305s；缓存命中 0.0–0.8s）→ 改"**全量（`--force`，本机 ~300s；缓存命中毫秒级）**"；单次 2494s 异常样本列为待核 |
+
+---
+
+## 二、治理规则（本场共识，供后续文档维护）
+
+1. **单一事实源**：文档不做第二事实源。**有唯一事实源 → 一律引用**（版本号 →
+   `package.json`；选项 → `--help`；报告字段 → `design.md §观测面契约`；状态 →
+   `check_status` 定义处；容量 → `design.md §二`）——**与 churn 无关**；
+   **无事实源 → 补一行 + 增删同步**（成本按变更频率分级，如 `scripts/` 清单）。
+2. **三类改法优先级**（复述类问题）：**删复述引权威 > 最短准确陈述**（无权威入口的
+   行为描述）**> 就地改准确**（必须保留语境时）。
+3. **两条判据**：① **重复"计算"在冷路径可接受；重复"事实"在文档不可接受**
+   （报告两遍遍历不做合并；文档复述必去）。② **数字必须带口径**（测点/样本/是否
+   `--force`；"单点数字不宜当承诺"）。
+
+---
+
+## 三、矛盾清单（哪个对—依据）
+
+| A 处 | B 处 | 哪个对 |
+|---|---|---|
+| `README.md:79` + `AGENTS.md:214-215` + `design.md:273-274`："兜底 `mv-*` 并警告" | `design.md:315-321`（决策 15）+ `observability.py:68-80/90-91/831-833` + `extensions/multi-viewers-say/index.ts:13`："无降级兜底、未匹配报错" | **B**（代码双重注释 + 决策 15 三重互证；A 为 e2e16 裁定删除前的旧文案残留） |
+| `AGENTS.md:216`（0.3.0；同段 `:32` 又说"发版待办"） | `package.json:3` = 0.5.0 + tag v0.4.0/v0.5.0 | **B**（版本号唯一事实源） |
+| `design.md:395-396`（AFT ≈2%、几乎无剩余收益） | `design.md:459`（同插件 445.9s） | **B**（按生产规模实测；A 为小 session 外推） |
+| （同一文档内）`design.md:530` 标题重复两遍 | — | 排版事故 |
+
+---
+
+## 四、缺失项清单（代码有、文档零字）
+
+| 机制 | 代码位置 | 为什么该写 | 建议写在哪 |
+|---|---|---|---|
+| 分析目录代码副本（快照语义） | `start_discussion.py:416-419` · `:710` | 调试"改了主仓为什么不生效"的必经问题；**副本非事实源**边界必须写清 | `AGENTS.md` 架构节 + `design.md` |
+| 无产出重试（E4） | `meeting_engine.py:51` | 固定成本乘数项（最坏 +2.5–4.5 分钟/轮） | `design.md` 协议机制节 |
+| stall 兜底 600s（E5） | `meeting_fs.py:52` | 死锁墙钟下限；"接管"语义未文档化 | 同上 |
+| `scripts/check-residue.sh`（S3） | `scripts/check-residue.sh`（多处被方法论引用） | 清单声称列 `scripts/` 却漏项 | `AGENTS.md:26-27` 一行 |
+
+---
+
+## 五、明确不做（防止把设计当缺陷）
+
+1. **不合并四层文档**（README 用户 / AGENTS 开发 / design 决策 / 方法论测试）——
+   职责边界不同；问题不是"文档多"，是"同一事实被复述"。
+2. **不删决策记录**（含被否决方案与已失效决策 19 的标记）——记录"当时为什么"是其职责。
+3. **不合并 `observability` 两个报告遍历函数**（`_report_session_metrics` /
+   `_report_session_levels`）——职责分割 > 遍历次数；报告是冷路径。
+4. **不枚举 prompt 主流程命令**——低 churn + 执行自足优先（prompt 的"状态列举"例外：
+   已漂移，按 T5 处理）。
+5. **不把历史决策段/追溯编号（"审核#N"等）当缺陷**——AGENTS.md 注释引用约定已声明
+   不可核验、行为以自描述为准。
+
+---
+
+## 六、待核（不猜）
+
+- `README.md:162` 计时样本中**单次 2494s**（≈8× 中位，2026-09-11）的成因（疑似机器
+  负载/挂起，未查）。
+- `not-exists` 是否应进用户文档的**常规列举**——按 #1③ 改法（不枚举）后该问题自然消解；
+  若将来选择保留枚举，需产品口径决定。
+
+---
+
+## 七、收敛记录
+
+- 三方在自由讨论后进入 round-robin：**效率 / 简单 / 铁律 均 `pass`**（无异议）。
+- 通过条件的核验点：`#1 ①②③`、`#2 E1`、`#3` 含 **E3** 与 **T4 两处**（及 M1、S3≡M3、
+  E2+E7、E4/E5、README:162 口径）——均收录于本清单。
+- 引线以精确版为准：决策 15 = `design.md:315` 起（`520-529` 为决策 20 退役段，作废）；
+  E3 B 处 = `design.md:459`；第三抄本 = `design.md:273-274`；T6 = `design.md:105`。
+
+---
+
+*本结果为三方共识，非单方观点；各视角原始分析与交锋记录见本讨论目录各 `work-*/` 消息
+（目录将在 cleanup 时删除）。*

package/docs/reviews/README.md

@@ -31,6 +31,7 @@
 | `2026-09-13-e2e21-postfix-review.md` | 审阅 `5e02a67`（并验证报告口径修复） | AFT legacy 检测 4 组路径**多一层 `aft/`**（死检查 + 静默假阴性）；子串预筛是对设计的错误陈述；`n`/`sec` 分母不一致导致均值低估 | `5cc0b5e` 之后的批 |
 | `2026-09-13-e2e23-time-breakdown-analysis.md` | 一次分析的**时间构成**（哪些必要、哪些可省） | AFT / MC historian 两笔分钟级开销都不在报告里；反对"不等退出就推进"与"新增常驻机制" | `98786d6` + `c46d996` / `9deefac` |
 | `2026-09-14-e2e24-extension-policy-review.md` | 扩展策略三档（默认 mc-tools）的实现与证据链 + `ctx_search` 价值评估 | **S1：缺 MC 的降级路径提前 return → 命令被截断（缺 model/print/注入、cwd 错）**；S1a 测试判别力不足；E2 报告缺"声明 vs 生效"；E1 成本口径超出精度；T1–T3 文本矛盾；F5/F6/F7/S2/F9 解析链缺陷；**ctx_search 9 次调用全为问卷诱导、0 次决定性帮助、命中 1 条过期记忆** | `91a1171`（Batch 1+3）、`b9329fb`（Batch 2 删死代码）|
+| `2026-09-14-e2e25-doc-drift-review.md` | 文档 vs 代码一致性（文档漂移）+ ctx_search 的**自然使用**观察 | **三处文档仍写"兜底 mv-* 并警告"而代码是无兜底、未匹配报错**（行为语义相反）；README 缺 `--extension-policy`；报告字段列表过期；4 条缺失项；**根因 = 对实现的复述**（治本：引事实源不复制）；自然使用观察：`ctx_search` **0 次**、historian 0 次 | `ba204ef` |
 
 ## 环境口径（读报告时的背景）
 

package/observability.py

@@ -120,8 +120,6 @@ def check_status(base):
         return "not-exists"
     # 读路径统一走 fs.run_git（quotepath 加固单点；run_cmd 只做一次性
     # 环境命令——init/clone/config/push）
-    # 读路径统一走 fs.run_git（quotepath 加固单点；run_cmd 只做一次性
-    # 环境命令——init/clone/config/push）
     agents = meeting_fs.read_protocol(bare).get("participants", [])
     # "收尾完成"判据**单源** = human_viewer.is_finished（concluded 且
     # HEAD:result.md 有效）——与 viewer 的 done 同一判据（§3.5-P5：此前

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-multi-viewers",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Multi-perspective analysis for Pi: fork the main session into N perspective agents over the meeting protocol.",
   "type": "module",
   "private": false,

package/prompts/multi-viewers.md

@@ -86,7 +86,7 @@ argument-hint: '"<主题>"'
 ## 收尾（用户驱动）
 
 ```bash
-mv.sh --status      # done/stopped/running（目录可省略——自动定位当前分析）
+mv.sh --status      # 状态 + [result] 路径（目录可省略——自动定位当前分析）
 ```
 
 - `done`：读上一步打印的 `[result]` 路径（产物固定位；**路径由命令给出，