pi-multi-viewers 0.2.2 → 0.4.0

package/AGENTS.md

@@ -23,13 +23,15 @@ spec_gen.py          spec 生成层（question/骨架/viewers 校验与快照/ag
 observability.py     观测层（check_status / --report / --wait / loop 存活检测）
 human_viewer.py      【human 通道】只读展示（增量/--follow/游标）
 human_sayer.py       【human 通道】插话命令（单次/stdin/交互 -i）
-scripts/mv.sh        wrapper（prepare/start/status/wait/cleanup/view/say）
+scripts/mv.sh        稳定入口 shim（exec mv_cli.py；路径被 prompt/README 引用）
+scripts/pi-probe.sh  LLM 探针（跑 pi + 登记新 session → 残留检查器可追溯）
+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 注册；发版待办）
 templates/           AGENTS.md.tpl / agent.md.tpl / gitignore.tpl / spec-readme.md.tpl
-viewers/             示例视角（性能/简单/铁律——仅是形态示例，视角内容由用户按需自定）
+viewers/             示例视角（效率/简单/铁律——仅是形态示例，视角内容由用户按需自定）
 docs/examples/first-experiment/  首次实验存档（机制验证 + 模板原型 + 真实消息）
 docs/reviews/        自我审阅存档（多视角自审 result.md 原文 + 索引/口径说明）
 tests/               测试（unittest discover tests）
@@ -51,6 +53,19 @@ tests/               测试（unittest discover tests）
 祖先发现）+ spec background.md（人工可选边界约定——prepare 蒸馏机制已
 移除，fork 使其冗余；background 只写显式边界，不复述对话）。
 
+**agent 进程环境**：`GIT_CEILING_DIRECTORIES`（git 上溯防护）——注入点
+`meeting_loop._spawn_env`。**扩展策略（决策 20）：默认零扩展** ——
+`--no-extensions --no-skills --no-prompt-templates --no-themes`，只留 pi 内置
+工具与项目内 AGENTS.md。为什么：两类插件在**我们这种 session 形态**上都是分钟级
+负担、且都在关键路径上（loop 等进程退出才继续）——
+· **AFT**：大 session 上进程退出前多活数分钟（受控对照 445.9s → 0.5s）；
+· **MC**：它的 historian 对"带大段未处理历史"的 session **每次必失败并立刻重试**
+（受控对照：同输入 **447s → 10.3s，43 倍**）。
+零扩展**真场实测**：墙钟 12m31s / 每次唤醒 48.1s / 收尾≈0% / historian 0 次。
+加回扩展 = **显式 opt-in**（`--extensions` / 协议 `extensions: true`），且须自证
+净收益（design.md 决策 20 的门槛条款）。**主 pi 完全不受影响**（只改我们 spawn 的
+agent 进程命令行；主 pi 的 MC/历史学家照常）。
+
 **关键约定**：pi sessions 目录编码 = `--` + 去首尾斜杠内斜杠换 `-` + `--`
 （`/tmp` → `--tmp--`；wrapper 解析 fork 源依赖它，编码错一根横线 = 静默
 解析不到——已加显式报错）。**fork-only fail-fast**：缺 fork 源 = 明确报错
@@ -155,6 +170,14 @@ loop、状态从 git 共享事实推导、单一事实源 = protocol.json、无
 3. 失败现场保留了吗（测试失败删 log = 测试白跑）？
 4. 改装置/用新 API 先做秒级最小实验验证语义了吗（不跑长测试试错）？
 
+**LLM 运行两条纪律（2026-09-13 定，机制在 `scripts/pi-probe.sh`）**：
+① **当次确认**——判据按**预估时长**（秒级冒烟免批；预计 ≥30s、多轮唤醒、整场分析
+必须先取得用户当次同意），**"后台跑、不占用户终端"不是豁免理由**；
+② **跑完先汇报**——任何真实 LLM 运行结束后先把结果报给用户并停下等指示，**不得
+连续追加第二批实验**。机制：`pi-probe.sh --approved "<凭据>"`（无凭据拒绝执行）+
+运行账本 `~/.pi/pi-multi-viewers-llm-runs.log` + 脚本收尾提醒；e2e 讨论走 spec
+审阅闸门。详见方法文档 #25。
+
 **方法条目仓库**：全部具体方法（git 写前 pull / 进程检测 / 失败三分类 /
 装置对齐 / 运行观察分离 / 参数形态矩阵二维 / 不留 session / 隔离 +
 用例级 teardown / 失败保留现场）及历史实例，统一在
@@ -176,7 +199,7 @@ loop、状态从 git 共享事实推导、单一事实源 = protocol.json、无
   extension × 1（multi-viewers-say 插话：零 LLM，直接 spawn human_sayer.py；
   目录发现 = `<cwd>/mv-<sessionId>-*` 最新，兜底 `mv-*`（排除
   `mv-spec-*`）并警告）
-  + wrapper。**npm 已发布 0.2.2（2026-09-11）**。
+  + wrapper。**npm 已发布 0.3.0（2026-09-12）**。
 - **开发机安装（两步，缺一不可；2026-09-10 实测）**：
   ① `pi install /root/pi-multi-viewers`——**注册包**（写
   `~/.pi/agent/settings.json` 的 `packages` 数组）；pi 不是"扫 node_modules

package/README.md

@@ -1,7 +1,7 @@
 # pi-multi-viewers
 
 多视角协同分析（Pi 插件）：把主 pi session **fork** 成 N 个视角 agent，
-各带一份视角任务书（性能/简单化/安全/……），在 meeting 协议下交锋、
+各带一份视角任务书（效率/简单/铁律/……），在 meeting 协议下交锋、
 修正、收敛，产出一份共识结果。
 
 与 [pi-agents-helper](https://github.com/maxdai/pi-agents-helper)（多方
@@ -102,7 +102,7 @@ scripts/mv.sh --view                          # 一次性增量查看（主 pi
 # 插话 / 状态 / 收尾（目录可省略——自动定位本 session 当前分析）
 scripts/mv.sh --say "<文本>"                   # 插话（命令行形态；pi 内用 /multi-viewers-say）
 scripts/mv.sh --status                        # running / done / stalled / stopped（done 时附 [result] 路径）
-scripts/mv.sh --report                        # 只读报告（流程/配额/进程/LLM；冷路径，不持久化）
+scripts/mv.sh --report                        # 只读报告（流程/配额/进程/LLM/档位对照；冷路径，不持久化）
 scripts/mv.sh --cleanup                       # 收尾（result.md 自动留存到 <dir>-result.md）
 ```
 
@@ -111,7 +111,7 @@ scripts/mv.sh --cleanup                       # 收尾（result.md 自动留存
 一个视角文件 = **一份视角说明**，纯内容、无格式要求（无 frontmatter、
 无需标题，**文件名就是全部元数据**）。三个要点（措辞经实验验证）：
 
-1. **单一 lenses**——写清这个 agent 用什么角度看（性能 / 简单化 / 安全 /
+1. **单一 lenses**——写清这个 agent 用什么角度看（效率 / 简单化 / 安全 /
    成本 / 用户体验 / ……），并要求"所有观点必须从该视角出发"
 2. **不越界**——写明"其它视角由别的参与者负责，你不要越界展开"
    （**不要**列举具体是哪几个视角——参与者会变，列举就会过期）
@@ -122,12 +122,14 @@ scripts/mv.sh --cleanup                       # 收尾（result.md 自动留存
 frontmatter 字段、写文件路径、独立参与者纪律。
 
 ```
-你是多视角分析中的"性能视角"参与者（agent 性能）。   ← ❌ 不要（脚本按文件名注入）
-你的所有观点必须从性能角度出发：复杂度、热点……        ← ✅ 视角内容
+你是多视角分析中的"效率视角"参与者（agent 效率）。   ← ❌ 不要（脚本按文件名注入）
+你的所有观点必须从运行效率角度出发：时间效率、运行效率…… ← ✅ 视角内容
 ```
 
 **规范**：≥2 个视角、内容非空、名字不含空白与路径分隔符、非 `human`、
 ≤32 字符——不合规在生成 spec 前就报错（零产物）。
+**以 `.` 开头的文件自动排除**（不参与、不报错）——临时屏蔽某个视角时
+改个名即可（如 `效率.md` → `.效率.md`）。
 视角之间**互补或对立都可以**，对立产生的分歧正是多视角分析的价值。
 
 ### 复用的三种方式（都不需要把视角写进命令行）

package/docs/design.md

@@ -98,10 +98,39 @@ compaction 的 `firstKeptEntryId` 起 + 其后的条目"——窗口内含 compa
 | `loop-<agent>.log` | loop + engine（stdout 重定向） | `[YYYY-MM-DDTHH:MM:SS.mmm] <agent>: <msg>` | 人（grep/肉眼）+ `--report`（**仅登记字段**） | **否** | O(1) 捕获 |
 | `wake-logs/<agent>-<epoch>.txt` | loop | `CMD: <shlex.quote 单行>` | 人（排错第一手段） | 否 | O(prompt) |
 | `status-<agent>.json` | loop | `{"sessionID": ...}` | 流程（崩溃恢复） | 是（恢复用） | O(1) |
-| `pi-sessions/fork-src-*.jsonl` | pi | 文档化 session schema | fork 构建 + `--report` | 否（报告用） | O(MB) 全量 → **禁轮询** |
+| `pi-sessions/fork-src-*.jsonl` | pi | 文档化 session schema（`usage`/`stopReason`/`timestamp`/`thinkingLevel`） | fork 构建 + `--report` | 否（报告用） | O(MB) 全量 → **禁轮询** |
 | `result.md`（固定位） | resultWriter loop | 结论文档 | 人 | 是（收尾判据） | — |
 | `--report`（视图） | observability | 文本行 | 人（**三个出口**，见下） | **否**（不得升级为验收 gate） | 冷路径一次性 —— **O(session 大小)**：每 agent 读整个 fork-src jsonl（实测 3 × 789KB ≈ 2.4MB/次、50–150ms/次，×3 出口 <0.3s/次分析），**不得进入任何轮询路径**（e2e16 评审量化） |
 
+**报告的字段集**（e2e17 评审后定稿）——**四组谓词分组 + 一组对照**，
+全部**只读已有家**（session 的文档化字段 + loop log 登记字段），不新增度量、
+不在 loop log 增记（同一事实两处 = 双写）：
+
+| 组 | 形状 | 落点 |
+|---|---|---|
+| `usage` 合计 | `{input, cacheRead, output, reasoning}` | 每 agent 一行；`reasoning ⊂ output`（**不可相加**），缺席省略括注 |
+| `requests_by_stopReason` | `{键=stopReason 原值: 计数}` | 与下一项同一行（`stopReason：toolUse 78（1234s）｜…`） |
+| `seconds_by_stopReason` | `{键=stopReason 原值: Δ 合计}` | 同上；**口径 = 相邻条目 Δ 合计**（每次唤醒首条响应**也计入**；跨唤醒空闲不进入 Δ——唤醒 prompt 本身是一条 user 条目，空闲落在"上一唤醒末条 → 本次 user 条目"之间）。⚠️ 曾短暂采用"首响不计时"，理由（跨唤醒空闲）经 e2e20 评审批证伪后**已撤回**（见决策 19 的 e2e20 修正段） |
+| `effective_levels` | `[thinkingLevel…]`（session 侧，去重保序） | `档位：声明 X ｜ 生效 Y ｜ ✓一致 / ⚠不一致` |
+| （对照）`declared` | `pi-agent.json.thinking` | 同上——声明值与生效值**并列**（此前从没人对照过：探测失败会静默取档，spec 表面正常） |
+| `终止` 行 | 分类 + 原料计数 | `终止：共识（RR 全体 pass）｜freezing N / all-freezing N / pass N / stall 接管行 N`；分类判据只有事实（bare 的 type 计数 + loop log 的"超时兜底/声明接管"字样）——**不做评分** |
+| `唤醒构成` 表 | 每次唤醒一行 + 每 agent 合计 | 四端点（spawn / 首事件 / 末事件 / exit）+ 往返数 + `Δ助手` + `Δ工具` + retry + 本唤醒内的 commit；合计给 `跨度 = 启动前 + 事件内 + 收尾` 与平均/往返/retry（e2e23 分析产出，见下） |
+
+**`唤醒构成` 表的精度契约**（e2e23 多视角分析定稿）：**可推导** = 分段 Δ、
+按 role 拆分、计数、retry、终止原因、区间重叠、离群 top-N；**不承诺** =
+单次调用内的 TTFT/生成拆分（session 只有完成时间戳，为它插桩的收益不支撑成本）。
+**纪律**：账用对账恒等式（`Σ(启动+事件内+收尾) = Σ进程跨度`——不等超 2s 时报告
+打印"时间源未对齐"事实行），**归因用成本模型**，两者不得混用；跨度阈值只作
+报告事实行，**不进代码分支**。
+
+两个设计要点：
+- **键 = `stopReason` 原值（含 `None`）**：名字即事实、不会过期——
+  `requests_tool/final` 这类解释性命名会因"长消息也是 `toolUse`"立刻过期。
+  键集合不随数据增长（新增同类数字只多一个键）；保留 `None` 键，否则
+  "计数相同、时长差两个数量级"的情形会静默丢失。
+- **provider 失败那笔账就在这里**：`error` 键同时给计数与时长——此前它
+  完全不可见（e2e13 实测 11% 墙钟零记录；e2e17 实测区间 11%–19%）。
+
 **报告的三个出口**（同一 `build_report`，同一份内容）：
 1. **`--follow` 结束**——viewer 在 done 分支自动附报告（`human_viewer._print_report`）。
    这是**用户通道自带**：用户执行 `!!` 命令就在结束时直接看到，**零 LLM 参与**
@@ -308,7 +337,158 @@ commit 是溯源记录、本节是长期引用点——不并存两份权威值
     一改就静默失配（LLM 会以为没报错而继续）。改为"命令非零退出 → 停下来
     读报错原文问用户"：判据降为退出码（wrapper 的 `fail()` 保证 `exit 1`），
     原因解释交还给输出原文。
-17. **git 守卫范围 = 从讨论 workdir 发起的操作**（`GIT_CEILING_DIRECTORIES`
+17. **CLI 层 = Python（bash 只留 shim）**：`scripts/mv.sh` 是 5 行 shim
+    （找到仓库根 → `exec python3 mv_cli.py "$@"`），解析/决议/调用/展示全在
+    `mv_cli.py`。**路径 `scripts/mv.sh` 不变**（prompt/README/用户习惯引用
+    它）。收敛依据不是"更整洁"，而是这层产出的真实 bug **全部出自 bash
+    陷阱**（`shift` 吃掉显式目录 = F5 回归、`local` 重复声明清空变量、命令
+    替换里的 `exit` 不进父 shell 致双重错误消息、参数静默丢弃 = P0），且
+    bash 在本项目工具链里**零行覆盖**（Python 覆盖率看不到它）——缺口只能靠
+    真实 e2e 或评审暴露。收敛后逻辑进入覆盖率与进程内单测
+    （tests/test_mv_cli.py），解析统一出口。子进程边界不变：start_discussion
+    / human_viewer / human_sayer 仍以子进程调用（各自是 CLI 入口）。
+    顺带三处"无静默"加固（bash 版是静默的）：status/report/wait/cleanup 的
+    多余参数响亮失败、`--say` 多于 2 个参数响亮失败（未加引号文本会被当成
+    目录）、`--view` 的 viewer 失败透传 rc 且**不打印 HEAD 游标**（给失败的
+    一轮发游标会让下一次 `--since` 静默跳过消息）。
+18. **配置自明性三件（e2e17 评审落地）**：
+    1. **spec 永远写显式 variant**——`models.md` 两个槽都显式（model 写
+       `default` = 继承本机；variant 缺省 = `DEFAULT_THINKING`）；探测失败
+       时打一行 stderr 提示（**可见**，不阻断——终端直用本就没有 `PI_*`），
+       而不是让 spec 表面正常、生效值静默取档。
+    2. **`variant` 槽没有 `default` 别名**——`default` 只在 model 槽有意义
+       （= 继承）。相邻两行同词反义会让读者必错，且别名不增加表达力
+       （空已是缺省）；写了 `default` 就按原值透传（可见失败）。
+       档位默认值单一声明点 = `meeting_fs.DEFAULT_THINKING`。
+    3. **fork 源不携带旧会话的 `thinking_level_change`**——本场档位由 CLI
+       显式传入（恒非空），旧条目既不是本场生效值、又会让 pi **跳过**写
+       自己的档位条目（`if (!hasThinkingEntry) append`）→ session 里没有
+       "本场生效档位"这个事实。剔除后 pi 在边界之后补写，报告才能并列
+       「声明值 vs 生效值」。`model_change` **不剔除**（无 `--model` 的路径
+       靠它回填主 pi 模型——活配置，不是陈旧副本）。
+19. **[已被决策 20 取代，整套机制已删除] agent 进程的作用域配置（XDG_CONFIG_HOME）——关 AFT 语义搜索**：
+    实测（2026-09-12）AFT 的**语义搜索**（本地 ONNX embedder
+    all-MiniLM-L6-v2）让每个 pi 进程多活约 **57 秒**：带语义搜索 61.0s、
+    关掉 3.3–4.4s、无扩展 2.2s（逐个扩展隔离 + 跨项目复现，非冷热/非竞争）；
+    而 agent 的 pi 进程退出**在唤醒关键路径上**（loop 等进程结束才继续）→
+    e2e17 那场 33 次唤醒 ≈ 墙钟 12 分钟 / 55 分钟（≈22%）。AFT 自己的日志
+    显示它在 ~2s 内已 shutdown 完毕，"多活的 57 秒"像 ONNX 运行时线程/句柄
+    残留（上游问题），我们不等它修。
+    **做法**：不改用户配置（**主 pi 完全不受影响**），而是在建环境时生成
+    `<base>/agent-config/`（`meeting_fs.build_agent_config`）——
+    `cortexkit/aft.jsonc` = 用户配置键原样保留 + 语义搜索关闭（新旧键名
+    都写）；`cortexkit/magic-context.jsonc` = 用户配置**逐字拷贝**（MC 行为
+    不变）；再由 `meeting_loop._spawn_env` 把该目录作为 agent 进程的
+    `XDG_CONFIG_HOME` 注入（**目录存在才注入**——老环境不改行为）。
+    影响面实测：pi 自身不读 XDG_CONFIG_HOME（dist 零命中）、mcp-adapter
+    不读、只有 MC 读（故拷贝）。副作用：agent 进程内
+    `$XDG_CONFIG_HOME/git/config` 也随之改变（协议本就禁止 agent 跑 git，
+    且有 GIT_CEILING_DIRECTORIES 兜底）。目录随讨论目录删除 → 零残留。
+    已知边界：AFT 还读项目级 `<project>/.cortexkit/aft.jsonc`，用户项目若
+    有该文件且显式开启语义搜索，可能覆盖本配置（本仓无该文件）。
+
+    **「完全屏蔽 AFT」——已评估，暂不做（用户 2026-09-12 定：先保持现状，
+    以后单独测试）**。事实与口径：
+    - 现状只关**语义搜索**，AFT 仍加载（trigram 索引、LSP、工具集、每 agent
+      一个 `aft` 索引服务）。剩余实测成本：无扩展 2.2s / 仅 MC 2.8s /
+      AFT（语义关）3.3–4.5s → **~1–2s/唤醒 ≈ 2% 墙钟**（33 唤醒 ≈ 1 分钟
+      / 55 分钟）。最初那 57s 已经拿回，**速度上几乎无剩余收益**。
+    - 三种屏蔽方式：`--no-extensions` + `-e <MC 扩展入口>`（AFT 不加载、
+      MC 保留；入口可从 `~/.pi/agent/settings.json` 的 `packages` + 包的
+      `pi.extensions` 解析，不硬编码）；`--pure`（全关，已实现）；现状。
+    - 保留 AFT 的两个非速度理由：① AFT 默认 `hoist_builtin_tools` →
+      agents 的 read/write/edit/bash 用的是 AFT 实现（**与主 pi 一致**），
+      屏蔽后行为会变；② 每 agent 一个 `aft` 索引服务并发访问主项目索引。
+    - **重估触发条件**：动机从“更快”变为“隔离/行为一致性”（如验证纯 pi
+      工具下 agents 表现、或担心并发索引）；届时做成**协议层开关**
+      （如 `agentsExtensions: default | no-aft | pure`）而非硬编码，保留
+      两种形态可 A/B。
+
+    **e2e19 自审（多视角审阅本次实现）修正三处**：
+    1. **键名方向写反**：AFT 现行键是 `semantic_search`，`experimental_
+       semantic_search` 是旧名（上游 `CONFIG_MIGRATIONS` 的 `oldKey`；读取端
+       `semantic_search ?? experimental_semantic_search`）。此前恒写**旧名**
+       → 靠迁移生效，上游一旦移除旧名即**静默回吐 57s**。现恒写现行名 +
+       **删除**旧名（并存会触发上游 migration-conflict 警告，我们没理由制造）。
+    2. **`_strip_jsonc` 会改写字符串值**（活着的 bug）：旧实现用逐字符状态机
+       跟踪字符串、却把尾逗号正则作用于整段拼接文本 → 字符串里的 `", }"` /
+       `", ]"` 被静默改写（结果仍是合法 JSON，`json.loads` 挡不住）。现按
+       **字符串切分**（`re.split` 保留分隔串，正则只作用于偶数下标 = 串外文本），
+       新增两条回归用例（先红后绿验证过：旧实现下红）。
+    3. **AFT 关不掉/有副作用的条件**（评审核到源码，此前 docstring 把
+       **确定覆盖**写成“可能覆盖”，并漏了用户侧副作用）：
+       - 项目级 `<project>/.cortexkit/aft.json[c]` 对安全名单键（含
+         `semantic_search`）**确定覆盖**作用域层，且上游**不打警告** → 目标
+         项目自己开了语义搜索时我们关不掉（主场景暴露，本机免疫）；
+       - 上游每个 pi 进程跑 `migrateAftConfigLocations()`，目标 =
+         `configHome()/cortexkit/aft.jsonc`——被我们的 XDG 注入换成**临时
+         副本**；legacy 源（`~/.pi/agent/aft/aft.json[c]`、`~/.opencode/aft/…`、
+         项目级 .pi/.opencode 同形）会因语义不同被 **`unlinkSync` 删除**并留
+         `.MOVED_READPLEASE`（指针指向将被 cleanup 删除的临时路径）；
+       - 新增 `meeting_fs.af_resolution_notes(project_dir, home_dir=None)`：
+         建环境时**命中才打印事实**（四条路径 × json/jsonc + `OPENCODE_CONFIG_DIR`
+         条件项），不判定、不评级、不进 `--report`；影响面（谁读 XDG）写成
+         **快照 + 重核动作**而非不变量。
+    4. **（e2e20 评审批修正，撤回两处错误）**：
+       - **边界判定改按字段**（`meeting_fs.iter_after_boundary`）：此前用子串
+         `BOUNDARY_TYPE in line` → 主 session 历史里含该字面量的普通条目
+         （引用它的 fixture 文本等）被当成边界 → **其后全部历史算进"本轮"**，
+         报告 LLM 段虚高 ~4 倍（实测：误判起点早 490 行；assistant 310→66、
+         Δ 40.7→9.8 分）。这也正是"Δ 合计 > 进程跨度"之谜的根因。
+       - **Δ 口径"首响不计时"撤回**：该方案基于上述错误归因（以为超量 Δ 来自
+         跨唤醒空闲）。实测证伪——每次唤醒都写 user 条目，空闲从不进入 Δ；
+         被排除的是每次唤醒首条响应的真实耗时。现恢复"相邻条目 Δ 合计"。
+       - **`_strip_jsonc` 改两趟法**：单趟"按字符串切分 + 奇偶下标"假设注释里
+         无引号 → `/* say "hi" */` 这类输入解析失败（**功能回归**，旧状态机
+         本是正确的）。现为"状态机只去注释 → 对无注释文本切分去尾逗号"。
+       - 其余：写入侧改用具名推导（S2）· 清单对齐上游 `paths.js`（用户级
+         OpenCode 根 = `configHome()/opencode` 非 `~/.opencode`；`.cortexkit`
+         上游只读 `.jsonc`）· 删测试专用参数 `home_dir` 与 `proj` 别名 ·
+         测试改强断言（不依赖进程环境变量）。
+    5. **gate 判配置文件而非目录**：目录在、文件缺的半成品状态照注入会让 AFT
+       静默回落默认（= 57s 回吐）。现判 `agent-config/cortexkit/aft.jsonc`
+       （具名推导 `agent_config_aft_file`，写入侧与判定侧共用），未注入时打一行
+       **事实**日志；`build_agent_config` 只返回 warnings（目录不再返回——
+       生产端本来就不用），并删掉只有测试在用的 `source_config_home` 参数。
+20. **agent 进程默认零扩展**（2026-09-13 用户定；取代决策 19 的"屏蔽 AFT、
+    保留 MC"）：
+
+    **证据（两类插件都在关键路径上，都是分钟级）**：
+    - **AFT**：大 session 上进程退出前多活数分钟——同一份 1.9MB session、同一模型
+      受控对照：全扩展收尾 **445.9s** vs 只留 MC **0.5s**。
+    - **MC**：它的 historian 对"带着大段未处理历史"的 session（agents 都是这种：
+      fork 自大历史）**每次必失败并立刻重试**——同一份 fork 源、同一极小任务受控
+      对照：**给 MC 447.2s（其中 435.5s 是 3 次连续失败的 historian、尾部占 97%）
+      vs 不给 MC 10.3s（43 倍）**。曾疑为 historian 模型 id 过期（已修，实测**仍然**
+      失败）→ 结论：对本项目的 session 形态，MC 的压缩机制**结构性不工作**。
+    - **真场验证（零扩展）**：墙钟 **12m31s** / 32 次唤醒 / **每次唤醒 48.1s** /
+      **收尾 ≈0%**（对照插件在场时 66–78%）/ **historian 0 次** / 并行度 2.42/3.0 /
+      档位对照 ✓。同一机制的对照：e2e19 71.6s·17m19s、e2e20 81.6s·20m34s、
+      e2e21 **330s·1h13m**（historian 风暴 62 次 60 失败）。
+
+    **做法**：默认唤醒命令带 `--no-extensions --no-skills --no-prompt-templates
+    --no-themes`（保留内置工具与项目内 AGENTS.md）；加回扩展是**显式 opt-in**
+    （CLI `--extensions` / 协议字段 `extensions: true`，`gen_protocol` **恒写**该
+    字段——默认 `false`）。**主 pi 不受影响**（只改我们 spawn 的 agent 命令行）。
+
+    **代价**：agents 用 pi 内置 read/write/edit/bash/grep/glob；无 `ctx_*` 与知识
+    注入。零扩展真场里三视角自述："内置工具胜任本任务、未因缺工具放弃或简化检查
+    （符号级导航多 2–3 步/文件）"——**自述 ≠ 测量**，但两次真场（e2e20、本场）
+    均抓到真问题（F1/S1 等），无质量下降证据。
+
+    **随此退役的机制**（删净、不留死代码）：`KEEP_EXTENSIONS`、
+    `resolve_extension_entries`、`--pure`（语义反转为默认）、以及决策 19 那整套
+    "作用域配置"（`build_agent_config`/`_strip_jsonc`/`af_resolution_notes` 等，
+    已先一步退役）。
+
+    **门槛条款（本场分析产出，写入设计纪律）**：任何"省时"提案先自证
+    `净收益 = 节省 − 机制自身成本 × 频率 − 失效代价（含检测延迟）`；凡需改
+    `meeting_engine`/`meeting_loop` 或新增常驻机制者，先过**审计三问**
+    （① 职责归属怎么变 ② 净收益数据来源 ③ 新增失败面与检测延迟），不得直接实施。
+    将来若要为 agents 加回任何扩展，须**显式 opt-in + 净收益账**（本次实证：
+    AFT/MC 两次都是"加了才知道贵"）。
+
+21. **git 守卫范围 = 从讨论 workdir 发起的操作**21. **git 守卫范围 = 从讨论 workdir 发起的操作**（`GIT_CEILING_DIRECTORIES`
    注入于 spawn）；主项目仓库不在守卫范围（agent 的 cwd 就是主项目，其
    约束归指令层 + 主项目 `.gitignore`）。要拦主仓库需换机制类（沙箱/钩子），
    经评估收益不支撑扩面。