pi-multi-viewers 0.8.0 → 0.8.1

package/AGENTS.md

@@ -233,7 +233,7 @@ loop、状态从 git 共享事实推导、单一事实源 = protocol.json、无
 
 ## 安装/发版状态（2026-09-11）
 
-- **当前形态**：prompt × 1（multi-viewers-setup 建视角）+ extension × 2
+- **当前形态**：prompt × 1（multi-viewers-setup 建视角）+ extension × 1（一单元注册三命令）
   ——一个扩展单元内注册三命令（`multi-viewers` 分析 / `multi-viewers-finish` 收尾 /
   `multi-viewers-say` 插话；前两个靠 CLI 机器标记行取值 `[prepare] spec=` /
   `[start] dir=` / `[start] watch=` / `[status]`，后者零 LLM 直接 spawn human_sayer.py；

package/docs/design.md

@@ -567,19 +567,23 @@ commit 是溯源记录、本节是长期引用点——不并存两份权威值
     内容起草仍是真 LLM 工作（任务类型/产出形态），故为**两段式**——骨架零 LLM，
     起草/摘要走普通对话；门禁取消则保留 spec，用户编辑后自行 `mv.sh --start`。
     **收尾状态语义（2026-09-25 评审）**：`running` 等待；`done | stalled` 并流进
-    "notify → confirm → cleanup"（`stalled` = 无存活 loop 的静止态，照 running 处理
-    会让用户等一个永不到来的收尾）；`stopped` 只提示手动清理。`stalled` 用独立文案
-    （其 result 由清理时保存，不复用 done 的"已留存"路径文案）；扩展是唯一守卫
+    "notify → confirm → cleanup"（照 running 处理会让用户等一个永不到来的收尾）；
+    `stopped` 只提示手动清理。**状态定义以 `observability.check_status` 为单一
+    事实源**（`stalled` = 有 result.md、无 concluded、loop 均不存活）——此处不复述其判据。
+    `stalled` 用独立文案（其 result 由清理时保存，不复用 done 的"已留存"路径文案）；扩展是唯一守卫
     （CLI 的 cleanup 无状态防护）。**本轮明确不做**（防翻案）：`--json` 输出模式、
     resume 新命令面、env 回退配置、`runCli` 超时、启动路径继续优化（已在 1–2s 地板）、
     给 stalled 加第三种动作。**契约例外**：扩展作为包内第一方消费者**直连**
     `mv_cli.py`（实测 shim 61ms vs 直连 58–66ms，性能上零差异；按契约一致性记例外一行）。
-      **UI 通道按 mode 分级（2026-09-25 实测）**：dialog（`select`/`confirm`/`input`/`editor`）
-      全模式可用（RPC/web 走请求-响应子协议、阻塞等用户；不带 `timeout` 即不倒计时，
-      暂停点成立）；`notify` 全模式可用（TUI = showStatus 行；pi-web = **追加进聊天流的
-      常驻行**，非瞬时提示）；**`setEditorText` 仅 TUI**——pi-web 忽略（`pi-web/static/app.js`
-      注释「set_editor_text … ignored」+ SDK `ui-context.ts` 里是空实现）。⇒ **交付观看命令
-      必须有 notify 兜底**（预填只是增强，不能当唯一出口）；需要分级时用 `ctx.mode`。
+    **UI 通道按 mode 分级（2026-09-25 实测）**：dialog（`select`/`confirm`/`input`/`editor`）
+    全模式可用（RPC/web 走请求-响应子协议、阻塞等用户；不带 `timeout` 即不倒计时，
+    暂停点成立）；`notify` 全模式可用（TUI = showStatus 行；pi-web = **追加进聊天流的
+    常驻行**，非瞬时提示）；**`setEditorText` 仅 TUI**——pi-web 忽略（`pi-web/static/app.js`
+    注释「set_editor_text … ignored」+ SDK `ui-context.ts` 里是空实现）。⇒ **交付观看命令
+    必须有 notify 兜底**（预填只是增强，不能当唯一出口）；需要分级时用 `ctx.mode`。
+    但 pi-web 实测**关掉 notify 弹窗即消失** ⇒ 观看命令还写一条 `pi.sendMessage`
+    （`customType: multi-viewers`、`display: true`）进消息流：持久可回滚复制，
+    代价 = 参与 LLM 上下文的一行（用户 2026-09-25 要求「message 流中也能显示」）。
     被否决：A（handler 里 `sendUserMessage` 触发 LLM 回合改 spec——时序不可控）、
     D（拆两条命令——把门禁成本转嫁用户；B1 变体/第三种即现形态）。
 

package/docs/reviews/2026-09-25-multi-viewers-postfix-review.md

@@ -0,0 +1,211 @@
+<!-- 存档：docs/reviews/2026-09-25-multi-viewers-postfix-review.md
+     来源：一次真实多视角分析的 result.md 原文（未删改，仅加本头与下方说明）。
+     分析场次目录已随 cleanup 删除；文中消息编号（如 效率/0012、铁律/0004）不可再核验，
+     仅作溯源线索（与代码注释引用约定一致：行为以自描述为准）。 -->
+
+# 存档说明
+
+- **主题**：复验 0.8.0 这批改动 —— extension 合并后的实现（一单元三命令）、
+  P1–P6 修复是否到位、扩展层 harness 的覆盖是否有漏
+- **场次**：`mv-mv-main-20260925-105614`（3 视角：效率 / 简单 / 铁律；真实 pi 讨论，
+  默认档 `mc-tools`、`forkMode=budget`、`maxMeeting=15`；三方共识收敛）
+- **复验判定**：P1–P6 **逐条到位**；合并（P5）判定**净简化**（`findPackageRoot`
+  全仓 1 定义 1 调用、旧目录不存在）；**未触碰唤醒路径** → 分析总时长期望零变化
+- **本场新抓（多数是上一批引入的）**：
+  - **漏 A（最重要，接线 bug）**：`run_tests.sh --reuse` 的错误成功信号 ——
+    `last_ok()` 只扫任意一行 `^OK`，而 harness 输出追加在 python 的 OK 之后 →
+    harness 失败时它仍为真；指纹又无条件写 → 下次 `--reuse` 命中并 exit 0 而日志含失败。
+    修法 **②′**：真跑前清指纹、`rc==0` 才写回（不变式「指纹存在 ∧ 匹配 ⇒ 最近同源真跑全绿」）。
+    本仓落地时做了同款三连红绿验证（全绿→指纹在；环境性失败→rc=1 且指纹已清；随后
+    `--reuse` 必须未命中→真跑）
+  - **D2**：启动通知「已预填进输入框」在 pi-web 为**不实断言**（`setEditorText` 仅 TUI）
+  - **B1**：`mv_cli.py` 两条人类行复用 `[start]` 契约前缀；**B2**：五处出路提示引用裸
+    `mv.sh`（不在 PATH 上，出路不可执行）
+  - **7 类现存分支零覆盖** + 两项装置缺口：**sid 注入零断言**（漏注入 = say/finish
+    静默定位失败而全绿）、harness 的 `new URL().pathname` 不还 percent-encoding
+  - **D1/D3** 文档漂移（AGENTS「extension × 2」；决策 22 复述 stalled 判据）
+- **落地**：`69a415a`（六文件一次收口；harness 28 → 44 断言，含 sid 装置与
+  `findPackageRoot` 直断 throw；先红后绿：去掉 sid 注入 → 3 条断言失败）
+- **本场暴露的用户可见事实**（不在代码里）：① 门禁暂停点**真的停住**（用户实测）；
+  ② pi-web 的 `notify` **关掉弹窗即消失** → 后续加第三交付出口
+  `pi.sendMessage`（custom_message 进消息流，`e92eacc`）
+
+# 0.8.0 复验 · 三方共识结果
+
+**主题**：复验 0.8.0 这批改动：extension 合并后的实现（一单元三命令）、P1–P6 修复是否到位、
+扩展层 harness 的覆盖是否有漏——只提意见，不改代码。
+**参与者**：效率 / 简单 / 铁律（3 视角；meeting 自由讨论 + round-robin 全体 pass）。
+**方法**：只读核对、每项带 `文件:行`；零 LLM 验证（harness 实跑、/tmp 逐字复刻门逻辑复现、
+grep/源码核对）；**未修改任何文件、未运行真实分析**。
+**场次**：`mv-mv-main-20260925-105614`（fork 模式 budget；mc-tools 档）。
+
+---
+
+## 0. 结论摘要
+
+1. **P1–P6 行为修复逐条到位，合并（P5）判定为净简化**：`extensions/multi-viewers/` 现为单一
+   单元、三命令（`index.ts` + `shared.ts`），逐字重复消失；**未触碰唤醒路径**
+   （48–82s/唤醒的大头一行未改，agent 注入内容未变）→ 分析总时长期望零变化，收益落在
+   人类交互层与维护期（效率/0001）。
+2. **本场共发现**：2 处新缺陷（漏 A：`--reuse` 错误成功信号；漏 B：P4 加载期分支无覆盖）、
+   3 处设计符合度偏差（D1/D2/D3）、2 处职责边界问题（B1/B2）、7 类 harness 覆盖漏 +
+   2 项装置缺口（sid 断言、percent-encoding）。**其中漏 A 的完整修法 ②′ 是本场最重要产出**
+   （三方认账，效率/0012、简单/0012）。
+3. **②′（铁律 0004 §二）**：`run_tests.sh` 的"失败不写指纹"（原方案②）**不能消除漏 A**——
+   同源码环境性失败会残留旧绿指纹，`--reuse` 仍命中 exit 0 而日志含失败（已复现）。
+   完整修法 = 真跑开始前 `rm -f "$FP_FILE"`、结束 `rc -eq 0` 才写回（:90 现为无条件写）。
+   不变式「指纹存在 ∧ 匹配 ⇒ 最近一次同源真跑全绿」，单一 rc 判据、零文本解析、覆盖中断。
+4. **净复杂度账为正（变简）**：S1 消 ≈35–50 行同构 spawn 样板、S2/S3 消软分支与 no-op、
+   批量条目多为 1–6 行改动；本批**零新装置**（新增能力仅 = 假 python3 多记一个 env 变量 +
+   导出 1 个函数 + 一个字符串常量）。
+5. **执行**：六文件一次编辑 → 一次 `/reload` → **约 5 分钟验证**（`run_tests.sh --force` +
+   零 LLM 门禁路径 + ②′ 红绿 ~10s）；**不专门真跑**（改动不触唤醒路径/协议注入/分析逻辑）。
+
+---
+
+## 1. 复验判定（0.8.0 本批 = dfe71cc 合并与 P1–P6）
+
+| 项 | 判定 | 依据（抽核） |
+|---|---|---|
+| **P1** stalled 并流 | ✓ 到位 | `index.ts` 状态分派：running 早退，`done｜stalled` 并流到 confirm→cleanup；harness 断言 stalled 不再落 running |
+| **P2** stalled 独立文案 | ✓ 到位 | stalled 不复用 done 的 result 路径文案；harness 断言不含 done fallback 文本 |
+| **P3** 删与暂停点矛盾的旧注释 | ✓ 到位 | 文件头现为「取消则不启动并保留 spec」，无「先取消再自行 start」旧句 |
+| **P4** 删单机回退、加载期响亮失败 | ✓ 到位 | 全仓 `FALLBACK_ROOT` 0 命中；`shared.ts` 找不到包根即 throw（行动性信息）；覆盖缺口见 §2.2 |
+| **P5** 合并为一单元三命令 | ✓ 到位 | `findPackageRoot` 全仓 1 定义 1 调用；旧 `multi-viewers-say/` 目录不存在 |
+| **P6** 取消提示 + harness 进仓库 | ✓ 到位 | 取消提示含「当前 pi session 内」；`tests/extension_harness.ts` 被 `run_tests.sh` 接入（缺 bun 可见跳过、`MV_REQUIRE_BUN=1` 严格、失败置 rc=1） |
+
+**复验实测**：harness **28 通过 / 0 失败**（口径更正：效率/0001 的 29 = `grep -c 'check('`
+含 1 处函数定义；运行汇总为 28）；harness 墙钟 **0.113–0.155s**（3 次，本机）——占全量
+（~250s 口径）≈0.05%，"反对 unittest↔harness 并行"由预测变为数据支撑。
+
+---
+
+## 2. 本场新发现（按类别）
+
+### 2.1 漏 A：`--reuse` 的错误成功信号 → 修法 ②′（最重要）
+
+- **机制**：`last_ok()` 只扫全日志任意一行 `^OK`（`run_tests.sh:50`），harness 输出**追加**在
+  python `OK` 之后 → harness 失败时 `last_ok` 仍真；指纹无条件写（`:90`）→ 下次 `--reuse`
+  命中（`:56-57`）并 **exit 0** 而缓存日志含 harness 失败。
+- **原方案②的残余洞（铁律 0004 复现）**：仅"失败不写指纹"时，**同源码环境性失败**
+  （`MV_REQUIRE_BUN=1` 缺 bun / 中断 / harness 并发）会残留上一轮旧绿指纹 → 仍命中 exit 0。
+  已用**逐字复刻的门逻辑**在 /tmp 复现（`→ REUSE 命中：exit 0（而 LAST_LOG 含 harness 失败）`）。
+- **②′**：真跑前 `rm -f "$FP_FILE"`；结束 `rc -eq 0` 才写回。`last_ok` 可留但**不能当 ② 的
+  替代**（它挡不住本反例）；②′ 后其定位退为"遗留指纹/篡改面"。
+- **红绿核验（3 条命令，同参数隔离源指纹）**：① module 全绿 → FP 存在；②
+  `env PATH=/usr/bin:/bin MV_REQUIRE_BUN=1` 同参数跑 → rc=1 **且 FP 不存在**；③ `--reuse`
+  → 必须"未命中→真跑"（现状会命中 exit 0）。
+- **三方裁决**：效率/0012、简单/0012 均认账采纳（补洞 + 单一 rc 判据 + 覆盖中断）。
+
+### 2.2 漏 B：P4 加载期失败分支无覆盖 → 内联（可裁）
+
+- `findPackageRoot` 未导出（`shared.ts:29`），harness 内 import 成功即无法触发；子进程负例
+  需**复制** `shared.ts` → 违反「测试对象 = 生产对象」（副本漂移）。
+- **裁定**：导出该函数直调、**只断言 throw**（至多含稳定标识 `pi-multi-viewers`）、不锁散文；
+  **残差明账**（锁函数、不锁加载期接线；坏掉症状=三命令消失，响亮）。
+- **内联本批**（不做事后追加：验证是批次级成本，事后追加=第二次验证循环）；优先级低，若砍
+  则记账留与下次改动同批（效率/0007 自我更正）。
+
+### 2.3 设计符合度偏差（D1/D2/D3）
+
+- **D1**:`AGENTS.md:236`「extension × 2」未随 P5 合并同步（同段已写"一个扩展单元内注册
+  三命令"）；`git show dfe71cc` 证实该行未动——"改了实现忘改抄本"的漂移。简单认领，改一行。
+- **D2**:启动通知「已预填进输入框，按 Enter 执行」在 **pi-web 为不实断言**
+  （决策 22:577-581 已写明 `setEditorText` 仅 TUI；复核 `pi-web/static/app.js:1907`、
+  `ui-context.ts:456` 空实现）——与 0.8.0 首用事故（预填被忽略）同源。
+  **修法：中性单串**（如「复制执行；TUI 下已预填」），**不引 `ctx.mode` 分支**（无 mock/断言
+  增量，断言体零改动，仅标签措辞随统一改名处理）；`setEditorText` 调用保留（TUI 增强）。
+- **D3**:决策 22:570 对 `stalled` 的复述（"无存活 loop 的静止态"）宽于单一事实源
+  （`observability.check_status`：**有 result.md**、无 concluded、loop 均不存活）——按字面
+  把 `stopped` 也涵盖。**扩展文案不改**（正常路径恒真），**决策 22 引用化**。
+  - **边界观察（简单/0007 读码定案，不进本批）**：status 判"有结果"看 `git log --all`，而
+    `preserve_result_md` 读 `HEAD:result.md`（`meeting_fs.py:1238`）→ 侧分支/删除场景可达性低；
+    **将来统一必须偏 loud**（危险方向 = 清理静默丢产物），不得选静默侧。
+
+### 2.4 职责边界问题（B1/B2）
+
+- **B1**:`mv_cli.py:368/371` 两条人类行复用 `[start]` 契约前缀且带路径（唯一契约清单外同前缀
+  行）——"方括号=机器契约"被稀释。修法：**去方括号**（非新增 `[spec]` 前缀）；已核
+  `test_mv_cli.py:312` 只断子串、零测试连锁。
+- **B2**:`index.ts:67/72/86/129/198` 五处出路提示引用裸 `mv.sh`，而 `which mv.sh` 为空、
+  README:55 教的是安装绝对路径 → 出路不可执行。修法：`shared.ts` 增**常量**
+  `MV_SH = \`bash ${PACKAGE_ROOT}/scripts/mv.sh\``，五处引用（PACKAGE_ROOT 现为模块私有，
+  常量化非抽象层）。
+
+### 2.5 harness 覆盖漏与装置缺口
+
+**漏场景（7 类，均为现存分支）**：① MV `!specDir`（rc=0 无 `[prepare] spec=`）② MV
+`!watch` ③ FIN 状态读取失败整支 ④ FIN cleanup 失败 ⑤ SAY find-dir 成功 + sayer 失败
+⑥ SAY 空输出（"插话已发送"）⑦ `[start] dir=` 缺失（按 §3-S2 定案 (b) 写作"→ 报错"）。
+补方式按"追加用例"（两处必然例外：S2 改成功夹具、sid 装置改 calls 输出格式）；断言名带
+分支标识（替代另立清单表——清单=第二抄本必漂移）；现有断言一并统一改名（纯改名零行为）。
+
+**装置缺口（本场新增两项）**：
+- **sid 传递零断言**：假 python3 只记 argv（`harness:25-31`）；sid 是 `mv-<sid>-*` 命名与
+  find-dir 的唯一钥匙，漏注入 = say/finish **静默定位失败**而 28 条全绿 → 假装置多记
+  `$PI_SESSION_ID` + 各命令断言（**升为防静默同级**）。
+- **`HERE = new URL(…).pathname`**（`harness:18`）不还原 percent-encoding——实测把
+  `extensions/` 与 harness 复制到 `/tmp/space test/repo` 运行即报
+  `Cannot find module '/tmp/space%20test/repo/…'`；改 `fileURLToPath`（与生产 `shared.ts`
+  同处理）。
+
+---
+
+## 3. 冻结的批次清单（六文件、一次收口）
+
+**编辑顺序**（依赖者后写；S1 与 harness 无强依赖，真依赖仅 S2→#7 场景、D2 措辞→标签文案）：
+
+1. `extensions/multi-viewers/shared.ts`：S1 三 spawn 样板合一（原语 ≤~15 行、三调用点语义
+   逐一保留：stderr 合并与否 / rc vs ok / env 差异；**不顺手给 sayer 注入 sid**——现语义照抄）
+   + `MV_SH` 常量 + 漏 B 导出（+头注释契约行同步）
+2. `mv_cli.py`：S2 定案 **(b)**（`!dir` 并入 guard，删三元；dir 契约项保留）+ B1 去方括号
+3. `extensions/multi-viewers/index.ts`：D2 中性文案 + B2 用 `MV_SH` + S3 删三处
+   `getArgumentCompletions: () => null`（`argumentHint` 保留——上游扩展命令映射未转发，
+   留着将来生效）
+4. `tests/test_mv_cli.py`：S2 断言微调（如需）
+5. `tests/extension_harness.ts`：7 类场景 + sid 装置/断言 + `fileURLToPath` + 断言名统一
+   （含现有断言）+ 漏 B 用例（导出直调、只断 throw）
+6. `tests/run_tests.sh`：漏 A **②′**（真跑前清指纹 + `rc==0` 才写回）
+
+**文档两行**：D1（`AGENTS.md:236`）、D3（决策 22 引用化）。**可裁顺序**：A 防静默 → B 用户
+可见 → C 文档 → D 简化（漏 B 用例可裁，但要砍则记账留与下次同批）。
+
+**批次约束**：零新装置、不触碰唤醒路径；验证 = `run_tests.sh --force`（~250s）+ `/reload`
+零 LLM 走"假主题到门禁取消"（数十秒，顺带见到 D2/B2 新文案）+ ②′ 红绿（~10s）。
+
+---
+
+## 4. 明确不做 / 边界记录
+
+- **不专门真跑**本批（改动全在扩展/CLI 人类输出/测试/文档层；不触唤醒路径与协议注入）。
+- `last_ok()` 本批**不动**（对修复前遗留指纹有保护面；其精简留待下批评估）。
+- **stalled+取消** 场景低价值可裁（两表均未列）。
+- D3 的 `--all` vs `HEAD` 判据分叉：记为边界观察，**不进本批**；将来统一偏 loud。
+- S2 的 (a)（删 `[start] dir=`）**留作将来因其它原因动契约时的清理候选**（本批不划算：
+  7–8 处连锁 + doc×3 漂移面；简单/0008、效率/0008 均持此记录）。
+- `argumentHint` 上游未转发：保留，随上游补丁生效（不属本仓缺口）。
+
+---
+
+## 5. 收敛过程（消息索引）
+
+- **效率**（0001–0012）：墙钟四层账（唤醒是大头、extension 层非瓶颈）+ 省时账（P1 最大、
+  harness 性价比最高）+ 反对常驻/框架/并行/再弹 dialog；发现漏 A 并给出两方案 → 认账转 ②；
+  对漏 B"导出 vs 子进程"更正为内联；提供批内编辑顺序与"不专门真跑"验证分级；0002 提出
+  "补场景必须与修 `last_ok` 同批"的联动点。
+- **简单**（0001–0012）：S1/S2/S3 三处简化主张（spawn 样板合一、dir 半必填二选一、
+  删 no-op 字段）+ 反对过度抽象三条 + harness 覆盖表 + 主张"断言名带标识替代清单表"；
+  读码定案 D3（`--all`/`HEAD` 分叉，比两边原表述更细）；B2 提出 `MV_SH` 常量；
+  在 S2 (b)/(a) 与漏 B 口径上随证据两度更新立场。
+- **铁律**（0001–0007）：首轮以三条铁律逐项检视（P1–P6 到位 + D1/D2/D3 + B1/B2 + harness
+  六类 + 两项装置缺口）；裁决漏 B（导出+只断 throw）、漏 A（②）、S2 语义、S1 验收三条；
+  认账并裁定 S2 定案 **(b)**；**发现并复现 ② 的残余洞，给出完整修法 ②′**（本场最重要产出）；
+  复核 D2/D3 并记录 loud 方向；round-robin pass 收口。
+
+---
+
+## 6. 一句话结论
+
+**0.8.0 的合并与 P1–P6 修复复验通过（harness 28/28、零行为反例）；需在下一批补齐
+②′（漏 A 完整修法）、7 类覆盖漏与 sid/路径两装置缺口、以及 5 处文案/文档偏差（D1/D2/D3、
+B1/B2）——全部为 1–6 行级、零新装置、不触唤醒路径，一次收口 + 约 5 分钟验证即可。**

package/docs/reviews/README.md

@@ -33,6 +33,7 @@
 | `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` |
 | `2026-09-25-multi-viewers-extension-review.md` | 把 `/multi-viewers` 改成 extension 这次的实现（extension 代码 / CLI 机器标记行契约 / 文档同步） | **P1：`stalled` 被当成 running → 让用户等一个永不到来的收尾**（唯一行为错误）；P2 `[result]` 只在 done 打印；P3 头注释与暂停点自相矛盾；P4 `/root/pi-multi-viewers` 单机死回退；P5 两扩展逐字重复 ≈35 行且已漂移（→ 合并为一单元三命令）；P6 取消提示缺 sid 提醒 + **扩展消费端零仓库内测试**；首用另暴露：主题带引号、观看命令只有预填一个出口 | 本批（合并 + P1–P6 + 首用两项 + harness 进仓库） |
+| `2026-09-25-multi-viewers-postfix-review.md` | 复验 0.8.0 的 extension 合并与 P1–P6（含 harness 覆盖审查） | **P1–P6 逐条到位、合并净简化**；新抓 **漏 A：`run_tests.sh --reuse` 的错误成功信号**（harness 失败仍算绿 → 命中旧绿 + exit 0，修法 ②′ 清指纹 + rc==0 才写回）；D2 通知里的不实断言（pi-web 忽略 `setEditorText`）；B1/B2 契约前缀与不可执行出路；7 类现存分支零覆盖 + sid 注入与 percent-encoding 两装置缺口；D1/D3 文档漂移；S1–S3 简化 | `69a415a`（+ `e92eacc` 第三交付出口） |
 
 ## 环境口径（读报告时的背景）
 

package/extensions/multi-viewers/index.ts

@@ -16,14 +16,17 @@
  *
  * 与 CLI 的契约（标记行/退出码）与全部原语见 ./shared.ts。
  *
- * 观看命令交付 = `ctx.ui.setEditorText` 预填输入框（按 Enter 即执行）**并**
- * 在 notify 里带一份（预填会被后续输入覆盖——只留预填这一个出口，用户就
- * 再也找不到它；2026-09-25 首次真实使用暴露）。
+ * 观看命令交付 = **三个出口**（缺一不可，都是实测暴露的）：
+ * ① `ctx.ui.setEditorText` 预填输入框（按 Enter 即执行；**仅 TUI**，pi-web 忽略）
+ * ② `notify` 带一份（即时可见；但 pi-web 上关掉弹窗即消失）
+ * ③ `pi.sendMessage` 写一条 custom_message 进消息流（**持久可回滚复制**；
+ *    代价 = 参与 LLM 上下文的一行）
  */
 
 import {
   findCurrentDir,
   grab,
+  MV_SH,
   runCli,
   runSayer,
   specListing,
@@ -35,7 +38,6 @@ export default function register(pi: any) {
   pi.registerCommand("multi-viewers", {
     description: "多视角协同分析：生成 spec → 你审阅 → 启动（零 LLM 流程）",
     argumentHint: "<主题>",
-    getArgumentCompletions: () => null,
     handler: async (args: string, ctx: any) => {
       const topic = stripQuotes(args.trim());
       if (!topic) {
@@ -64,12 +66,12 @@ export default function register(pi: any) {
         "启动多视角分析？（现在暂停中，可在其它窗口修改 spec）",
         `spec：${specDir}\n文件：${specListing(specDir)}\n\n` +
           "需要修改就去改这个目录，改完点「确认」继续；\n" +
-          "点「取消」则不启动（spec 保留，可稍后 mv.sh --start）。",
+          "点「取消」则不启动（spec 保留，可稍后 " + MV_SH + " --start）。",
       );
       if (!go) {
         ctx.ui.notify(
           `已取消，spec 保留在：${specDir}\n` +
-            `之后可在**当前 pi session 内**用：mv.sh --start ${specDir}\n` +
+            `之后可在**当前 pi session 内**用：${MV_SH} --start ${specDir}\n` +
             "（外部终端执行时目录名不带 session id，插话/收尾命令定位不到它）",
           "info",
         );
@@ -80,20 +82,29 @@ export default function register(pi: any) {
       const start = await runCli(["--start", specDir], cwd, sid);
       const watch = grab(start.output, "[start] watch=");
       const dir = grab(start.output, "[start] dir=");
-      if (start.rc !== 0 || !watch) {
+      if (start.rc !== 0 || !watch || !dir) {
         ctx.ui.notify(
           `启动失败：\n${start.output || "(无输出)"}\n` +
-            "可用 mv.sh --status 查看环境状态。",
+            "可用 `" + MV_SH + " --status` 查看环境状态。",
           "error",
         );
         return;
       }
 
-      // ④ 观看命令：预填进输入框 + notify 里留一份副本（见文件头）
+      // ④ 观看命令：三个出口（见文件头）——预填（仅 TUI）+ notify（即时）+ 消息流（持久）
       ctx.ui.setEditorText(watch);
+      // 消息流里留一条持久记录：用户实测 pi-web 的 notify 会随弹窗关闭而消失，
+      // 关了窗口就再也找不到这行命令。custom_message 进会话（**参与 LLM 上下文**，
+      // 一行开销），在用户空闲时追加 → 立即显示、可回滚复制（agent-session.ts:
+      // 非 streaming + 无 triggerTurn → _appendCustomMessage，不触发回合）。
+      pi.sendMessage({
+        customType: "multi-viewers",
+        content: `多视角分析已启动：${dir}\n观看命令（复制执行，不进 LLM）：\n${watch}`,
+        display: true,
+      });
       ctx.ui.notify(
-        `分析已启动${dir ? `：${dir}` : ""}\n` +
-          "观看（已预填进输入框，按 Enter 执行；也可复制这行）:\n" +
+        `分析已启动：${dir}\n` +
+          "观看（复制执行；TUI 下已预填进输入框）:\n" +
           `${watch}\n` +
           "插话：/multi-viewers-say <文本>　收尾：/multi-viewers-finish",
         "success",
@@ -104,7 +115,6 @@ export default function register(pi: any) {
   // ---------------------------------------------------------------- 收尾
   pi.registerCommand("multi-viewers-finish", {
     description: "收尾：查状态 → 确认 → 清理分析目录（结果留存；摘要走对话）",
-    getArgumentCompletions: () => null,
     handler: async (_args: string, ctx: any) => {
       const sid = ctx.sessionManager.getSessionId();
       const st = await runCli(["--status"], ctx.cwd, sid);
@@ -126,7 +136,7 @@ export default function register(pi: any) {
       if (state === "stopped") {
         ctx.ui.notify(
           "分析已结束但未生成结果（状态 stopped）。" +
-            "要清理请自行运行 mv.sh --cleanup。",
+            "要清理请自行运行 `" + MV_SH + " --cleanup`。",
           "warning",
         );
         return;
@@ -179,7 +189,6 @@ export default function register(pi: any) {
   pi.registerCommand("multi-viewers-say", {
     description: "向正在进行的多视角分析插话（human 消息，各视角可见可回应）",
     argumentHint: "<插话内容>",
-    getArgumentCompletions: () => null,
     handler: async (args: string, ctx: any) => {
       const text = args.trim();
       if (!text) {
@@ -195,7 +204,7 @@ export default function register(pi: any) {
         ctx.ui.notify(
           "本 session 没有正在进行的多视角分析（cwd 下无 " +
             `mv-${sid}-* 分析环境）。先用 /multi-viewers 启动，` +
-            "或改用 mv.sh --say <目录> \"<文本>\" 显式指定。",
+            "或改用 `" + MV_SH + " --say <目录> \"<文本>\"` 显式指定。",
           "error",
         );
         return;

package/extensions/multi-viewers/shared.ts

@@ -25,8 +25,11 @@ const PKG_NAME = "pi-multi-viewers";
  *  **找不到就响亮失败**（评审 P4）：此前回退到 `/root/pi-multi-viewers` 是单机
  *  死分支——触发条件（包被拆散/复制）恰恰发生在开发机以外，回退只会把"包根
  *  解析失败"变成更晚、更难诊断的失败。这里在**加载期** throw，错误信息给出行动。
+ *
+ *  导出仅供测试直调（断言 throw；不锁散文措辞）——加载期接线本身无覆盖，
+ *  残差明账：坏掉时症状 = 三个命令消失（响亮）。
  */
-function findPackageRoot(start: string, pkgName: string): string {
+export function findPackageRoot(start: string, pkgName: string): string {
   let dir = start;
   for (let i = 0; i < 8; i++) {
     try {
@@ -52,26 +55,48 @@ const CLI = path.join(PACKAGE_ROOT, "mv_cli.py");
 const SAYER = path.join(PACKAGE_ROOT, "human_sayer.py");
 const OBSERVABILITY = path.join(PACKAGE_ROOT, "observability.py");
 
-/** 运行 mv_cli 一条命令；返回 { rc, output }（stdout+stderr 合并）。 */
-export function runCli(
+/** 稳定的 CLI 入口（给用户的出路提示用）——裸 `mv.sh` 不在 PATH 上，
+ *  按此常量给绝对路径（评审 B2：出路必须可执行）。 */
+export const MV_SH = `bash ${PACKAGE_ROOT}/scripts/mv.sh`;
+
+/** 跑一次子进程并收输出。三处调用点的差异全部显式化（合并前是三份样板）：
+ *  `sid` 决定是否注入 PI_SESSION_ID（目录名与 find-dir 的唯一钥匙）；
+ *  `mergeStderr` 决定 stderr 是否并进同一缓冲（不并时必须 resume 掉，否则管道满阻塞）。 */
+function capture(
   args: string[],
-  cwd: string,
-  sid: string,
-): Promise<{ rc: number; output: string }> {
+  opts: { cwd?: string; sid?: string; mergeStderr?: boolean } = {},
+): Promise<{ code: number; output: string }> {
   return new Promise((resolve) => {
-    const proc = spawn("python3", [CLI, ...args], {
-      cwd,
-      env: { ...process.env, PI_SESSION_ID: sid },
+    const env = opts.sid
+      ? { ...process.env, PI_SESSION_ID: opts.sid }
+      : process.env;
+    const proc = spawn("python3", args, {
+      cwd: opts.cwd,
+      env,
       stdio: ["ignore", "pipe", "pipe"],
     });
-    let out = "";
-    proc.stdout.on("data", (d) => (out += d.toString()));
-    proc.stderr.on("data", (d) => (out += d.toString()));
-    proc.on("close", (code) => resolve({ rc: code ?? 1, output: out.trim() }));
-    proc.on("error", (e) => resolve({ rc: 1, output: String(e) }));
+    let output = "";
+    proc.stdout.on("data", (d) => (output += d.toString()));
+    if (opts.mergeStderr) {
+      proc.stderr.on("data", (d) => (output += d.toString()));
+    } else {
+      proc.stderr.resume(); // 丢弃但必须消费
+    }
+    proc.on("close", (code) => resolve({ code: code ?? 1, output }));
+    proc.on("error", (e) => resolve({ code: 1, output: String(e) }));
   });
 }
 
+/** 运行 mv_cli 一条命令；返回 { rc, output }（stdout+stderr 合并）。 */
+export async function runCli(
+  args: string[],
+  cwd: string,
+  sid: string,
+): Promise<{ rc: number; output: string }> {
+  const r = await capture([CLI, ...args], { cwd, sid, mergeStderr: true });
+  return { rc: r.code, output: r.output.trim() };
+}
+
 /** 取机器可读标记行的值（`[label] value`）；没有 → null。 */
 export function grab(output: string, label: string): string | null {
   for (const line of output.split("\n")) {
@@ -116,37 +141,21 @@ export function specListing(specDir: string): string {
  *  判据 = **退出码**（不是 stderr 文案——中文提示一改就静默失配，e2e16 F2）：
  *  rc 0 → stdout 是绝对路径；rc 1 → 未找到（无同 sid 分析）。无降级通道
  *  （不会回退到"项目下最新"——那会插错分析，e2e16 F1）。 */
-export function findCurrentDir(cwd: string, sid: string): Promise<string | null> {
-  return new Promise((resolve) => {
-    const proc = spawn("python3", [OBSERVABILITY, "--find-dir"], {
-      cwd,
-      env: { ...process.env, PI_SESSION_ID: sid },
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    let out = "";
-    proc.stdout.on("data", (d) => (out += d.toString()));
-    proc.stderr.on("data", () => {}); // 原因只在 rc=1 时通知用户（见 handler）
-    proc.on("close", (code) => {
-      const dir = out.trim();
-      resolve(code === 0 && dir ? dir : null);
-    });
-    proc.on("error", () => resolve(null));
-  });
+export async function findCurrentDir(
+  cwd: string,
+  sid: string,
+): Promise<string | null> {
+  const r = await capture([OBSERVABILITY, "--find-dir"], { cwd, sid });
+  const dir = r.output.trim();
+  return r.code === 0 && dir ? dir : null;
 }
 
-/** 执行 human_sayer.py 一次插话。返回 { ok, output }。 */
-export function runSayer(
+/** 执行 human_sayer.py 一次插话。返回 { ok, output }。
+ *  现语义照抄（不注入 sid——sayer 用显式目录参数）。 */
+export async function runSayer(
   dir: string,
   text: string,
 ): Promise<{ ok: boolean; output: string }> {
-  return new Promise((resolve) => {
-    const proc = spawn("python3", [SAYER, dir, text], {
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    let out = "";
-    proc.stdout.on("data", (d) => (out += d.toString()));
-    proc.stderr.on("data", (d) => (out += d.toString()));
-    proc.on("close", (code) => resolve({ ok: code === 0, output: out.trim() }));
-    proc.on("error", (e) => resolve({ ok: false, output: String(e) }));
-  });
+  const r = await capture([SAYER, dir, text], { mergeStderr: true });
+  return { ok: r.code === 0, output: r.output.trim() };
 }

package/mv_cli.py

@@ -365,10 +365,10 @@ def cmd_start(spec_dir, extra):
     # 条件 = 观测到一次 launch 失败，或将来引入 resume/retry 通道。
     if fnmatch.fnmatch(os.path.basename(os.path.normpath(spec_dir)),
                        "mv-spec-*"):
-        print(f"[start] spec 已消费，删除（本工具生成形态）: {spec_dir}")
+        print(f"spec 已消费，删除（本工具生成形态）: {spec_dir}")
         shutil.rmtree(spec_dir, ignore_errors=True)
     else:
-        print(f"[start] spec 已消费（保留未删——非 mv-spec-* 形态）: {spec_dir}")
+        print(f"spec 已消费（保留未删——非 mv-spec-* 形态）: {spec_dir}")
 
     # 第 2 步：启动已有环境
     if _call([PYTHON, START_DISCUSSION, "--dir", dir_path,

package/package.json

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