pi-proactive 0.0.0-stage → 0.2.0-beta.2

package/README.md

@@ -1,3 +1,706 @@
-# Temporary Holding Version
+# pi-proactive
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+给 Pi 增加「主动」能力：**空闲时主动推进或提问、按时间点主动发起任务、多个会话之间对话协作**。
+
+本包是 Pi 的一个扩展包（`pi-package`），加载后提供：
+
+- `/proactive` 命令面：查看状态、开关主动性、排期任务、取消任务；
+- `schedule_task` / `message_agent` / `list_peers` **三个模型工具**：模型可以自己排活、给另一个会话发消息、**先查清有哪些对端在线/空闲/擅长什么再发**（`list_peers` 只读）；
+- 跨进程协作层：同机 Unix socket 实时通道 + 文件邮箱兜底 + 消息去重。
+
+---
+
+## 许可与分发（专有）
+
+**本软件是专有软件（proprietary），非开源：源码不公开，分发物只含编译后的 JavaScript 产物。**
+
+- 许可：`package.json` 的 `license` 为 `SEE LICENSE IN LICENSE`，协议正文 = 本包内的 `LICENSE` 文件（版权所有 / 仅限内部授权使用 / **禁止再分发** / 禁止反编译与再授权 / 授权期限与联系）。
+- **分发物不含任何 `.ts` 源码**：安装包里只有 `build/`（编译产物）、`skills/`、`README.md`、`CHANGELOG.md`、`LICENSE`。
+- 内部分发走 tarball（`tools/release-pack.sh` 产出 + sha256）；**安装必须先解包再以目录方式装**（直装 `.tgz` 会「显示成功」但宿主加载失败 —— 实测陷阱）。
+- 发布前必须跑 `bash scripts/ci/publish-preflight.sh --registry <url> --public`（检查私有协议 / 零 `.ts` 源码 / 无内部路径与文档 / 入口在包内）。
+
+## 安装
+
+### 方式 A：私有 npm 源（组织 scope，跨机器可用）
+
+```bash
+pi install npm:pi-proactive
+```
+
+- 当前发布：`0.2.0-beta.1`（dist-tag `beta` / `latest`），integrity `sha512-q+fSY0OvPp8BeH1MGWSWqkhoVIjmZbQmd2ry5sPAQsqL8pvAQs0i1VrrAaLvy6Tds1l3fS01yBm/XzTl2bS9mQ==`
+- 校验下载到的制品是否与发布一致：`npm view pi-proactive@0.2.0-beta.1 dist.integrity`
+- **供应链缺口（如实披露）**：本次发布**未带 npm provenance**（本地发布无法生成；发布工作流模板见 `scripts/ci/publish-npm.yml`（复制到 `.github/workflows/` 后生效，需 GitHub token 的 `workflow` scope），**后续版本**将从 CI 发布并自动带 provenance）。
+
+### 方式 B：本地目录 / tarball（离线或内部试用）
+
+```bash
+pi install ./pi-proactive          # 本仓库内
+bash pi-proactive/tools/release-pack.sh --out ./dist   # 产出**全量交付束**：tarball + sha256 + 交付目录 + zip + manifest，并跑四项自检（新鲜度/内容/校验记录值/zip 一致）
+pi install ~/.pi/packages/pi-proactive   # 先解包再按目录装（见下）
+```
+
+> 宿主会把安装源记成**相对路径** → 请把包放在**稳定目录**里、不要移动它。
+
+
+```bash
+# 作为 pi 包安装（写入 ~/.pi/agent/settings.json）
+pi install ./pi-proactive
+
+# 本地试用：只加载扩展本体，不写入设置
+pi --extension ./pi-proactive/extensions/proactive.ts
+```
+
+宿主自带的包（`@earendil-works/pi-coding-agent`、`@earendil-works/pi-agent-core`、`typebox`）只声明为
+`peerDependencies`（`"*"`），由宿主提供，**不随本包安装**（Pi 文档明确：把宿主包放进 `dependencies`
+会产生物理副本、绕过扩展模块映射，导致重复类与重复注册）。
+
+> **版本约束**：本扩展的**全部宿主 API 断言只对 `@earendil-works/pi-coding-agent` 1.3.0 验证过**。
+> `package.json` 的 `engines.pi` 写作 `>=1.3.0`（最低可用版本），但**更高版本未验证** ——
+> 升级 pi 后可能出现行为变化，升级后请先重跑 runtime 探针再依赖本插件的自动行为。
+
+## 5 分钟快速上手（内测版）
+## 24×7 数字员工（常驻形态，**默认关闭**）
+
+需要一个**人不在场也在干活**的常驻代理时再开（它会真花你的账号额度）：
+
+```bash
+# 安装（幂等；macOS 用 launchd，Linux 用 systemd --user）
+bash <安装目录>/tools/daemon-install.sh
+
+# 看看它昨晚干了什么 + 有什么等你确认
+/proactive doctor
+```
+
+- **默认 `enabled=false` + 干跑** → 装了不花钱、不投递任何任务；
+- 开启后仍受**预算硬上限**约束（每小时/每日动作数；token 只做估算）→ 超限自动**降级为只观察**并记账；
+- **不可逆动作绝不自动执行** → 进人工确认队列，早间交班时呈现；
+- 形态：macOS `launchd`（KeepAlive）/ Linux `systemd --user`（Restart=always）；
+- 自愈：崩溃自动重启、幂等认领、半成品不重放；卸载用 `tools/daemon-uninstall.sh`（幂等、无残留）。
+
+
+
+面向**第一次拿到内测包**的同事，按顺序做这 5 步就能看到插件真的主动一次。
+
+### 步骤 1｜装什么、装在哪
+
+内测分发物是 **tarball + sha256 校验文件**（不是 git 仓库路径）：
+
+```bash
+# 拿到 tarball 后先校验
+cd <tarball 所在目录>
+shasum -a 256 -c pi-proactive-<版本>.tgz.sha256
+
+# 解包到一个**稳定目录**（内测包与仓库无关，但目录本身别乱挪 —— 见下面的说明）
+mkdir -p ~/.pi/packages && tar -xzf pi-proactive-<版本>.tgz -C ~/.pi/packages
+mv ~/.pi/packages/package ~/.pi/packages/pi-proactive
+
+# 以 pi 包的形式安装（写入 ~/.pi/agent/settings.json）
+pi install ~/.pi/packages/pi-proactive
+```
+
+> **为什么强调「稳定目录」**：`pi install` 会把安装源记进 `settings.json` 的 `packages`，
+> 记的形式是**相对 settings.json 所在目录的相对路径**（宿主行为，见 `docs/packages.md`）。
+> 所以只要**包目录本身不挪动**，仓库怎么移动、改名都不影响；
+> 但如果把包解到 `/tmp` 这类会被系统清理的位置，装完过一阵就会失效。
+> 建议固定用 `~/.pi/packages/pi-proactive`。
+
+也可以**直接从源码目录**装（开发场景，注意源码目录挪动后要重新 `pi install`）：
+
+```bash
+pi install ./pi-proactive            # 相对路径：相对 settings.json 所在目录解析
+pi install /abs/path/to/pi-proactive  # 绝对路径：宿主会换算成相对 settings.json 的相对路径
+```
+
+> 自己打内测包：`bash pi-proactive/tools/release-pack.sh --out <产物目录>`
+> → 产出 tarball + `.sha256` + **交付目录**（README / SKILL / ops / onboarding / LICENSE / CHANGELOG / DELIVERY / tools / tgz / sha256）+ **zip** + `manifest.json`（逐项 sha256 与大小）；幂等：同输入同字节。
+> 脚本**自检**四项，任一不符即非零退出：① 交付目录内的 tgz 与本次构建同哈希 ② 包内含 `src/peer-spawn.ts` 等当前能力文件 ③ `.sha256` 记录值与实算一致 ④ zip 与交付目录逐项一致。
+> 复验既有交付束（不重新打包）：`bash pi-proactive/tools/release-pack.sh --check-only --out <产物目录>`。
+
+### 步骤 2｜怎么确认装上了
+
+```bash
+pi list          # 列表里应出现 pi-proactive
+```
+
+再开一个会话，执行下面这条命令，**有回执**就算装上了：
+
+```
+/proactive status
+```
+
+### 步骤 3｜看一次状态（先看懂再动手）
+
+```
+/proactive status
+```
+
+输出是 7 行「人话 + 机器可读字段」，例如：
+
+```
+主动性：已开启 (enabled=true)
+空闲触发：关 (idleTriggerEnabled=false)
+空闲检测：关闭 (idleDetect=off)
+空闲计时：—（未启用） (idleForMs=1823)
+提问超时：2m (askTimeoutMs=120000)
+限制：最短间隔 5m (minGapMs=300000) · 每小时上限 6 (maxPerHour=6) · 静默时段 未设置 (quietHours=无)
+下次空闲触发：—（空闲触发未开启） (nextTriggerInMs=—)
+```
+
+最后一行会说明**为什么触发 / 为什么没触发**（排障先看这一行）。
+
+### 步骤 4｜让它第一次真的主动（两处都要改）
+
+装上后插件**默认不打扰**（`idleTrigger.enabled=false`）。要看到第一次主动，需要**两个开关**：
+
+```bash
+# (a) 打开空闲触发（内存态：只对当次进程有效，重启后回到配置文件里的设置）
+/proactive idle on
+#    ↳ 这一步同时会把 idleDetect 从 off 切到 input-only，否则开了也不会真的触发
+
+# (b) 把阈值调小（默认 10 分钟太久，等不到）——改配置文件后重启会话
+#     <agent-dir> = $PI_CODING_AGENT_DIR，未设置时是 ~/.pi/agent
+cat ~/.pi/agent/proactive/config.json
+```
+
+把 `config.json` 改成（只改这两处，其余字段保留）：
+
+```json
+{
+  "idleTrigger": { "enabled": true, "afterMs": 30000 },
+  "limits": { "minGapMs": 60000 }
+}
+```
+
+- `afterMs: 30000` = 空闲 30 秒就够触发（默认 600000 = 10 分钟）；
+- `minGapMs: 60000` = 两次主动之间至少隔 1 分钟（默认 300000 = 5 分钟）——
+  **不调它，即使阈值到了也会被冷却挡掉**（判定说明会显示「冷却中」）。
+
+改完重启会话，再 `/proactive status`，看 `nextTriggerInMs` 在往下走 → 到了就会主动推进一次。
+想立刻自检链路，可以用 `/proactive test`（**强制**投递，绕过冷却与频率上限）。
+
+### 步骤 5｜怎么关掉
+
+```
+/proactive off        # 关闭主动性总开关（已落盘，重启后仍生效；已排期任务保留）
+/proactive idle off   # 只关空闲触发（内存态）
+```
+
+`/proactive on` 可以再打开。彻底卸载见下面「卸载与回滚」。
+
+---
+
+## 典型场景脚本（可直接复制）
+
+> 在 Pi 会话里直接粘贴命令；`#` 开头是注释，可以一起粘。
+
+### 场景 1｜空闲时主动汇报进度（最常用）
+
+```
+# 打开空闲触发并把阈值压到 30 秒（内存态部分 + 配置文件部分见「步骤 4」）
+/proactive idle on
+```
+
+配置里设：
+
+```json
+{
+  "idleTrigger": {
+    "enabled": true,
+    "afterMs": 30000,
+    "intent": "wake",
+    "prompt": "用户已空闲，请用一句话汇报当前进度，并给出下一步建议。"
+  },
+  "limits": { "minGapMs": 60000, "maxPerHour": 6 }
+}
+```
+
+效果：用户停手 30 秒后，插件自己起一轮，把这段提示词投给模型，模型回一句话。
+**恢复安静**：`/proactive idle off`。
+
+### 场景 2｜定时提醒（喝水 / 站起来 / 收工）
+
+```
+/proactive in 30m 起来活动一下，喝口水
+/proactive at 18:30 该收工了，保存一下今天的进度
+/proactive every 2h 看一下构建有没有挂
+```
+
+- `in <时长> <内容>`：时长后触发一次（`30s` / `10m` / `2h` / `1d` / 纯数字按秒）；
+- `at <HH:MM> <内容>`：到当天该时刻触发（**已过则顺延到明天**）；
+- `every <时长> <内容>`：按间隔重复。
+
+查任务 / 取消：
+
+```
+/proactive tasks              # 看 id、排期类型、相对到期、intent、归属、开关
+/proactive cancel <id>        # 取消（id 从上一条里抄）
+```
+
+> ⚠️ 定时任务与主动触发**共用同一个冷却闸门**：默认 `minGapMs=300000`（5 分钟），
+> 到点投递**可能顺延最多约 5 分钟**。要准点，把 `limits.minGapMs` 调小。
+
+### 场景 3｜跨会话提问与回复（两个会话之间）
+
+会话 A（发起方）直接跟模型说：
+
+```
+用 message_agent 工具给会话 "builder" 发一条 kind="ask" 的消息：
+标题「进度同步」，正文「你那边跑到哪一步了？还剩什么没做完？」。
+```
+
+会话 B（对端）会收到提问，模型回答后**自动回送一条 reply**（携带原 `correlationId`）。
+
+- 手工点名也可以：在会话 A 里执行 `/proactive peers` 看在线 peer 的**名字与 agentId**；
+- 对端**必须也装了本插件**，否则消息不会被消费；
+- 对端**离线**也能发：消息落盘到对端邮箱，等对方**以同一 sessionId 重启**后取回
+  —— 这种情况下回执是 `queued`（**已落盘、尚未送达**，不是「已送达」）。
+
+### 场景 4｜让模型自己排活（`schedule_task` 工具）
+
+跟模型说：
+
+```
+帮我把「每 30 分钟检查一次 CI」排成一个重复任务，用 schedule_task 工具，when 传 30m。
+```
+
+模型会调用 `schedule_task` 真正落库（进任务表、进程退出后仍在），到期由调度器投递。
+
+### 场景 5｜只看不改（值班/观察模式）
+
+```
+/proactive status             # 总览 + 为什么触发/为什么没触发
+/proactive tasks              # 待触发任务
+/proactive peers              # 在线 peer、心跳、当前任务
+```
+
+只读这三条不会产生任何投递动作。
+
+---
+
+## 卸载与回滚
+
+### 停用（推荐先做这步）
+
+```
+/proactive off        # 主动性总开关关闭（已落盘）；已排期任务保留在任务表里
+```
+
+### 彻底卸载（三步）
+
+```bash
+# 1) 卸包
+pi remove <安装时用的包路径或包名>
+#    或直接编辑 ~/.pi/agent/settings.json 的 "packages" 数组，删掉 pi-proactive 那一项
+
+# 2) 删运行期数据目录（可选，但这是「彻底」）
+#    数据目录 = <agent-dir>/proactive/
+#    <agent-dir> = $PI_CODING_AGENT_DIR，未设置时是 ~/.pi/agent
+rm -rf ~/.pi/agent/proactive          # 先确认路径！别手抖删错目录
+
+# 3) 确认
+pi list                                # 列表里不应再有 pi-proactive
+```
+
+### 数据目录在哪、删了会丢什么
+
+数据目录：`<agent-dir>/proactive/`（默认 `~/.pi/agent/proactive/`），目录权限 `0700`、文件 `0600`。
+删掉它 = **删掉本机全部运行期数据**：
+
+| 删掉的东西 | 后果 |
+|---|---|
+| `tasks.json` | **所有排期任务消失**（不可重建：排期只有这一个来源） |
+| `mailbox/` | 未处理 / 待重试 / 已归档的消息**全部消失**（对端可能一直在等这些消息的回复） |
+| `processed/`（含 `seen.json`） | 去重账本消失 → 窗口内的重复消息会被**重新处理**（不丢消息，但会重复动作） |
+| `threads/` | 线程日志（审计 + 轮次计数）消失 → 轮次上限判定失准（可能多跑几轮） |
+| `agents/` | 在线名单消失 → 对端暂时找不到你（重新启动会话会重新注册） |
+| `config.json` | 配置回到默认值（`enabled=true`、`idleTrigger.enabled=false`） |
+| `run/*.sock` | socket 端点（进程退出时会自动清理；僵尸端点下次启动会重建） |
+
+> **只想静音、不想丢数据**：只做 `/proactive off`，**不要**删数据目录。
+
+### 回滚到旧版本
+
+```bash
+# 1) 备份当前数据（回滚前必做）
+cp -a ~/.pi/agent/proactive ~/.pi/agent/proactive.bak.$(date +%s)
+
+# 2) 装回旧版
+pi install <旧版本包目录>
+
+# 3) 重启会话，用 /proactive status 确认读到的是旧版配置
+
+# 4) 若旧版读不懂新版数据（新版写了旧版不认识的落盘版本号）→ 恢复备份
+#    rm -rf ~/.pi/agent/proactive
+#    cp -a ~/.pi/agent/proactive.bak.<时间戳> ~/.pi/agent/proactive
+```
+
+当前落盘格式版本是 `v1`，**没有 `version` 字段的文件按 `v1` 读**（升级不丢数据），
+所以在版本号不变的前提下，**回滚不需要动数据**。
+
+---
+
+## 反馈渠道（内测）
+
+**报给谁**：直接报给**发给你这个 tarball 的同学**（内测发包人）；也可以在本仓库开 issue 记录。
+
+**请一并带上这三样**（缺一样都很难复现）：
+
+1. **版本**：`pi-proactive` 的版本号（tarball 文件名里就有，如 `0.2.0-beta.1`）；
+2. **`/proactive status` 的完整输出**（它含 `enabled` / `idleDetect` / `minGapMs` /
+   `maxPerHour` / `quietHours` / `nextTriggerInMs` 与「为什么触发/为什么没触发」的判定说明）；
+3. **宿主版本**：`pi --version`（本扩展的宿主 API 断言只对 pi 1.3.0 做过验证）。
+
+**再附上**（有则更好）：复现步骤、期望 vs 实际、插件 stderr 里带 `[proactive]` 前缀的日志片段、
+`<agent-dir>/proactive/` 下相关文件（如 `tasks.json`、某个信封）。
+
+---
+
+## 内测边界（**先知道这些，免得误判**）
+
+这是**内测版**，以下四条是**当前已知边界**，不是待修的 bug 清单：
+
+1. **跨机行为未验证** —— 跨主机（共享目录 / NFS）只有落盘排队（约一个轮询周期，秒级），
+   掉线或过期都可能导致消息不被处理。**内测期请限定同机使用。**
+2. **无鉴权** —— 威胁模型是「同 UID 可信」：同 UID 的任意进程可以往邮箱写文件并冒用 `from`。
+   **本插件不是安全边界**，不要用它防御同机其它进程。
+3. **TUI 完整链路未验证** —— 真人按键下的「提问 → 回答 → 回填」完整闭环只做了部分场景抽验
+   （见 `docs/review/tui-smoke.md` 自述的 7 项未验证项）；rpc / json / print 等非交互模式的降级行为有实测。
+4. **定时投递可能被 5 分钟冷却顺延** —— 排期任务与主动触发共用同一个冷却闸门
+   （默认 `limits.minGapMs=300000`），到点投递**可能晚约 5 分钟**。要准点就调小 `minGapMs`。
+
+其它未验证项（长时驻留 > 10 分钟、`every` 的小时级节拍、跨模型家族独立复验等）
+见下方「能力边界与限制」一节，那里是**逐条如实列出**的完整清单。
+
+
+---
+
+## 命令（Usage）
+
+Usage: `/proactive <子命令>`。下表**逐条对应实现里实际注册的分支**（`src/commands.ts` 的命令处理
+`switch`），未列出的子命令会被拒绝并提示可用清单。
+
+> **命令面真源 = 实现**：下表由 `scripts/gen-doc-tables.sh` 从 `pi-proactive/src/commands.ts` 的
+> `SUBCOMMANDS` ＋ `switch (sub)` 的 case 分派**自动生成**（共 **16 个命令**），**不要手改**；
+> 要改命令面请改实现，然后跑 `bash scripts/gen-doc-tables.sh --apply`（门禁 `scripts/check-doc-tables.sh` 校验）。
+
+<!-- BEGIN:GEN commands -->
+| 命令 | 参数形态 | 做什么 | 状态 |
+| --- | --- | --- | --- |
+| `/proactive status` | `无` | 总览：开关、空闲计时、待触发任务、对端在线、上次主动、本小时用量。 | 已实现 · `pi-proactive/src/commands.ts:550` |
+| `/proactive on` | `无` | 打开全部「代理自发」行为（空闲触发、模型自调度、跨会话自发请求）。 | 已实现 · `pi-proactive/src/commands.ts:565` |
+| `/proactive off` | `无` | 关闭全部「代理自发」行为；已排期任务保留但不再触发。 | 已实现 · `pi-proactive/src/commands.ts:566` |
+| `/proactive test` | `无` | 立即模拟一次触发（走完整「护栏 → 投递」链路），用于验证主动能力是否真的生效。 | 已实现 · `pi-proactive/src/commands.ts:644` |
+| `/proactive tasks` | `无` | 列出所有待触发任务（编号 / 类型 / 下次到期 / 归属 / 触发次数）。 | 已实现 · `pi-proactive/src/commands.ts:647` |
+| `/proactive cancel` | `<id>` | 取消一个任务。 | 已实现 · `pi-proactive/src/commands.ts:673` |
+| `/proactive idle` | `on\|off` | 打开 / 关闭空闲触发并设定阈值（on 可带时长参数，省略 = 用上次设定）。 | 已实现 · `pi-proactive/src/commands.ts:713` |
+| `/proactive peers` | `[--all\|--idle\|--name <子串>\|--detail <agentId>]` | 列出已注册的对端与在线状态（名字 / 忙闲 / 最后心跳）；可加 --all / --idle / --name / --detail。 | 已实现 · `pi-proactive/src/commands.ts:586` |
+| `/proactive spawn` | `[名字]` | 创建一个对端会话（子进程 pi --mode rpc）；本会话退出时一并终止。 | 已实现 · `pi-proactive/src/commands.ts:621` |
+| `/proactive in` | `<时长> <内容>` | 排一个延迟任务（默认只属于当前会话）。 | 已实现 · `pi-proactive/src/commands.ts:691` |
+| `/proactive at` | `<HH:MM> <内容>` | 排一个绝对时间任务。 | 已实现 · `pi-proactive/src/commands.ts:692` |
+| `/proactive every` | `<时长> <内容>` | 排一个周期任务。 | 已实现 · `pi-proactive/src/commands.ts:693` |
+| `/proactive help` | `无` | 打印命令速查表（命令表 / 配置键 / 最常见故障 / 详细文档路径）。 | 已实现 · `pi-proactive/src/commands.ts:728` |
+| `/proactive history` | `[peer\|me] [条数]` | 查看最近的主动行为记录（时间 / 类型 / 目标 / 结果 / 被护栏拦下的原因）。 | 已实现 · `pi-proactive/src/commands.ts:651` |
+| `/proactive doctor` | `[--json]` | 只读体检：逐项健康判定 + 处置建议（--json 机器可读）；不打扰、不耗额度。 | 已实现 · `pi-proactive/src/commands.ts:558` |
+| `/proactive tell` | `<peer> <内容> [--kind ask\|task\|notify]` | 人侧给另一个会话下指令（--kind ask\|task\|notify，缺省 ask 要回话）；回信落回本会话。 | 已实现 · `pi-proactive/src/commands.ts:641` |
+<!-- END:GEN commands -->
+
+排期命令的排期结果会**当场回执**（任务 id、相对到期、绝对到期），任务**落盘**在任务表里，进程退出后仍在，
+下次启动继续按表调度。
+
+> 注：`/proactive quiet` **不是命令**（输入会被拒绝；静默时段是配置项 `limits.quietHours`）；
+> `/proactive notify` **不是命令**（`notify` 是消息语义 `kind:"notify"`，由模型工具 `message_agent` 承载，
+> 人侧给对端下指令用 `/proactive tell`）；`/proactive history [peer|me] [条数]` **已实现**。
+> 各命令的**行为细节**（落盘 / 内存态、参数怎么写、失败怎么提示）见下方「典型场景脚本」「配置」「排障」三节。
+
+---
+
+## 模型工具
+
+<!-- BEGIN:GEN tools -->
+| 工具 | 参数 | 作用 | 定义位置 |
+| --- | --- | --- | --- |
+| `schedule_task` | prompt（必填）：任务提示词<br>intent（可选）：投递意图，默认 wake（取值：wake \| interrupt \| queue \| notify）<br>askUser（可选）：触发时是否向用户提问（仅本地）<br>when（可选）：触发时间：时长（10m）/ 时刻（18:30）/ ISO 8601；缺省按 10m 处理 | 预约一个稍后触发的任务（真正落库到任务表，到点由调度器投递）。when 支持时长（10m）、时刻（18:30）或 ISO 时间；缺省按 10m 处理。 | `pi-proactive/extensions/proactive.ts:624` |
+| `message_agent` | to（必填）：目标 agent 的名字或 agentId<br>kind（可选）：消息语义（对方要不要回我）；缺省 notify（取值：notify \| ask \| task \| reply \| broadcast）<br>subject（可选）：标题<br>body（必填）：正文<br>intent（可选）：投递意图（怎么投给对方）；缺省 wake（取值：wake \| interrupt \| queue \| notify）<br>threadId（可选）：话题 / 会话 id（可选） | 给另一个正在运行的 agent 会话发消息（跨进程协作）。对端在线时走 socket 直达；不在线时消息落盘到对端邮箱，待其上线后处理。 | `pi-proactive/extensions/proactive.ts:669` |
+| `list_peers` | name（可选）：名字子串（大小写敏感；也命中 agentId）。同名歧义时返回与 message_agent 报错完全一致的候选<br>status（可选）：按在场状态过滤（online = 在线 = 空闲 ∪ 忙碌）（取值：online \| idle \| busy \| offline）<br>capability（可选）：按能力标签过滤（如 message_agent）<br>includeOffline（可选）：是否包含离线对端（缺省 false = 只给在线） | 列出本机可见的其它 agent 对端（名字 / agentId / 在场状态 / 心跳龄 / 能力标签 / 在途任务数 / 传输方式），可按名字、状态、能力过滤。**只读**：不产生任何对外行为。发消息前先查它（先查后发），别盲发 —— 离线对端现在打扰它不合适。 | `pi-proactive/extensions/proactive.ts:743` |
+| `proactive_query` | action（必填）：查询动作（与 /proactive 子命令同名）（取值：peers \| history \| status \| tasks \| doctor \| help）<br>name（可选）：peers：名字子串过滤<br>all（可选）：peers：是否包含离线对端<br>idle（可选）：peers：只看空闲对端<br>detail（可选）：peers：只看这一个 agentId<br>scope（可选）：history：范围（对端 / 我）（取值：peer \| me）<br>peer（可选）：history：按对端 agentId 过滤<br>limit（可选）：history：条数（1-200 的整数）<br>json（可选）：doctor：输出 JSON | 查询域：查对端（peers）/ 看主动行为历史（history）/ 看状态（status）/ 看任务（tasks）/ 只读体检（doctor）/ 看命令手册（help）。**只读**：不产生任何对外行为。 | `pi-proactive/extensions/proactive.ts:780` |
+| `proactive_schedule` | action（必填）：排程动作（与 /proactive 子命令同名）（取值：in \| at \| every \| cancel）<br>when（可选）：in/at/every：触发时间（时长 10m / 时刻 18:30）<br>content（可选）：in/at/every：任务内容<br>id（可选）：cancel：任务 id | 排程域：定时（in）/ 定点（at）/ 周期（every）/ 取消（cancel）。落到真实任务表，到点由调度器投递；与命令面 `/proactive in\|at\|every\|cancel` 同源。 | `pi-proactive/extensions/proactive.ts:806` |
+| `proactive_peer` | action（必填）：对端动作（与 /proactive 子命令同名）（取值：tell \| spawn）<br>peer（可选）：tell：目标对端（名字或 agentId）<br>content（可选）：tell：指令内容<br>kind（可选）：tell：指令类型（缺省 ask）（取值：ask \| task \| notify）<br>subject（可选）：tell：标题<br>thread（可选）：tell：线程 id<br>name（可选）：spawn：对端名字 | 对端协作域：给对端下指令（tell）/ 创建对端会话（spawn，受同时存活数上限）。tell 的目标解析与回执三态与命令面 `/proactive tell` 完全同源。 | `pi-proactive/extensions/proactive.ts:825` |
+| `proactive_manage` | action（必填）：管理动作（与 /proactive 子命令同名）（取值：on \| off \| idle \| test）<br>state（可选）：idle：开 / 关（取值：on \| off） | 管理域：主动性总开关（on/off）、空闲触发开关（idle）、自检（test）。这些能力属 human-gated：调用只会回报「需人工确认」并给出可复制的人工指令，**不会**自行改动全局开关。 | `pi-proactive/extensions/proactive.ts:847` |
+<!-- END:GEN tools -->
+
+> **模型工具面真源 = 实现**：上表由 `scripts/gen-doc-tables.sh` 从 `pi-proactive/extensions/proactive.ts` 的
+> `pi.registerTool({ name: … })` 注册项与参数 schema **自动生成**（共 **7 个模型工具**），**不要手改**；
+> 表中参数即真实 schema。下面三个小节是逐个工具的展开说明。
+
+### `schedule_task`
+
+预约一个稍后触发的任务（真正落库到任务表，到点由调度器投递）。
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| `prompt` | `string`（必填） | 任务提示词 |
+| `intent` | `"wake" \| "interrupt" \| "queue" \| "notify"` | 投递意图，缺省取配置里的 `idleTrigger.intent`（默认 `wake`） |
+| `askUser` | `boolean` | 触发时是否向用户提问（仅本地）。提问**必须带超时**；**用户取消**与**超时**是两个结局：取消 → **不消耗额度**、不记待答（只留一条 `declined` 审计事件）、文案「已取消」；超时 → **消耗额度**、记待答（`pending`）、文案「未在时限内收到回答，已记为待答」。额度**在提问有结论之后**才记账（回答 / 超时才扣，取消不扣）；提问窗口内不叠加提问与本机投递 |
+| `when` | `string` | 触发时间：时长（`10m`）/ 时刻（`18:30`）/ ISO 8601；**缺省按 `10m` 处理** |
+
+返回：`details.created === true` 时带 `taskId` / `dueAt` / `schedule`；参数非法或任务表未初始化时
+`details.created === false` 并带 `error` 文案。
+
+### `list_peers`
+
+**只读**查询对端目录：谁在线、谁空闲、谁擅长什么、有多少在途请求。
+
+- 参数：`name`（名字子串）｜`status`（`online`/`idle`/`busy`/`offline`）｜`capability`（能力标签）｜`includeOffline`（默认**只给在线**）
+- 返回：名字 / agentId / 在场状态 / 心跳多久前 / 能力标签 / 在途任务数 / 传输方式
+- **为什么要先查**：对端离线时打扰它不合适；多个对端同名时 `message_agent` 会因歧义直接报错 → `list_peers` 会把候选列给你
+
+### `message_agent`
+
+给另一个正在运行的 agent 会话发消息（跨进程协作）。
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| `to` | `string`（必填） | 目标 agent 的名字或 agentId |
+| `kind` | `"notify" \| "ask" \| "task" \| "reply" \| "broadcast"` | 消息语义（对方要不要回我），缺省 `notify` |
+| `subject` | `string` | 标题 |
+| `body` | `string`（必填） | 正文 |
+| `intent` | `"wake" \| "interrupt" \| "queue" \| "notify"` | 投递意图（怎么投给对方），缺省 `wake` |
+| `threadId` | `string` | 话题 / 会话 id（可选） |
+
+返回 `details.status`，共 8 种，**语义严格区分**：
+
+| status | 含义 |
+| --- | --- |
+| `accepted` | **已送达**：对端在线并已接收 |
+| `duplicate` | 对端已处理过这条消息，未重复投递 |
+| `queued` | **已落盘、尚未送达** —— 有两种语义，**都不得**写成「已送达」：① 对端**离线待上线**（消息写入对端邮箱，对方上线后才收到）；② 对端**在线但本轮未接收**（原因随附，如对端处理抛错 / 投递失败） |
+| `rejected` | 被拒绝（信封非法 / 参数非法 / 找不到目标 agent） |
+| `expired` | 消息已过期，对方不会再处理 |
+| `error` | 投递失败（写盘失败等） |
+| `unreachable` | 对端不可达（端点不存在或无进程监听） |
+| `timeout` | 等待回执超时（对端未在时限内回执） |
+
+> **`queued` 不是「已送达」。** 它有两种语义：**对端离线待上线**（消息落在对端邮箱，对方以**同一 sessionId** 重启后取回）与**对端在线但本轮未投递**（原因随附）。两种情况下对端都**尚未收到**。
+
+`kind:"ask"` 时，对端模型回答后会自动回送一条 `kind:"reply"`（携带原 `correlationId`、继承 `threadId`）。
+
+同一线程的**往返上限 = 4 轮**（只计**已完成的** reply；未获回答的提问不占额度；投递失败的回信不虚增计数）——
+达到上限后不再回信，并**必须通知请求方**（该通知走 **socket 优先 + 邮箱兜底**：离线请求方**也能收到**——落盘到其邮箱、待其上线后取回；去重粒度＝**(线程, 请求方)**，同一线程同一请求方只通知一次；见下方残余限制①）。
+
+---
+
+## 配置
+
+配置文件：`<agent-dir>/proactive/config.json`
+（`<agent-dir>` = `$PI_CODING_AGENT_DIR`，未设置时为 `~/.pi/agent`）
+
+```json
+{
+  "enabled": true,
+  "idleDetect": "off",
+  "askTimeoutMs": 120000,
+  "idleTrigger": {
+    "enabled": false,
+    "afterMs": 600000,
+    "intent": "wake",
+    "askUser": false,
+    "prompt": ""
+  },
+  "limits": {
+    "minGapMs": 300000,
+    "maxPerHour": 6,
+    "quietHours": { "from": "22:00", "to": "08:00" }
+  },
+  "peerWatch": {
+    "enabled": false,
+    "afterIdleMs": 600000
+  }
+}
+```
+
+<!-- BEGIN:GEN config -->
+| 配置键 | 默认值 | 作用 | 定义位置 |
+| --- | --- | --- | --- |
+| `enabled` | `true` | 主动性总开关（关掉则定时投递与空闲触发都不发生）。 | `pi-proactive/src/config.ts:336` |
+| `idleDetect` | `"off"` | 空闲检测档位：terminal（仅 TUI 生效）/ input-only（只靠输入事件刷新基线）/ off（关闭）。 | `pi-proactive/src/config.ts:337` |
+| `askTimeoutMs` | `120000` | 提问等待用户回答的超时（毫秒）。 | `pi-proactive/src/config.ts:338` |
+| `idleTrigger.enabled` | `false` | 空闲触发开关。默认关闭 → 装上插件不会立刻开始打扰。 | `pi-proactive/src/config.ts:340` |
+| `idleTrigger.afterMs` | `600000` | 空闲多久后触发（毫秒）。 | `pi-proactive/src/config.ts:341` |
+| `idleTrigger.intent` | `"wake"` | 空闲触发的投递意图。 | `pi-proactive/src/config.ts:342` |
+| `idleTrigger.askUser` | `未设` | 空闲触发时是否向用户提问。 | `pi-proactive/src/config.ts:432` |
+| `idleTrigger.prompt` | `""` | 空闲触发的提示词。 | `pi-proactive/src/config.ts:343` |
+| `limits.minGapMs` | `300000` | 两次主动触发之间的最短间隔（毫秒，护栏冷却）。 | `pi-proactive/src/config.ts:346` |
+| `limits.maxPerHour` | `6` | 每小时主动触发次数上限。 | `pi-proactive/src/config.ts:347` |
+| `limits.quietHours` | `未设` | 静默时段 {from,to}（HH:MM，from 大于 to 表示跨零点），时段内不主动打扰。 | `pi-proactive/src/config.ts:386` |
+| `peerWatch.enabled` | `false` | 跨会话空闲协作（peer watch）开关。 | `pi-proactive/src/config.ts:351` |
+| `peerWatch.afterIdleMs` | `600000` | 连续空闲多久后才去询问 peer（毫秒）。 | `pi-proactive/src/config.ts:352` |
+| `version` | `"v1"` | 落盘格式版本；无法识别时拒绝按已知格式解析（保留原文件，不覆盖）。 | `pi-proactive/src/config.ts:516` |
+<!-- END:GEN config -->
+
+> **配置面真源 = 实现**：上表由 `scripts/gen-doc-tables.sh` 从 `pi-proactive/src/config.ts` 的
+> `defaultConfig()` / `mergeConfig()` / `loadConfig()` **自动生成**，**不要手改**；
+> 键集合、默认值与定义位置都以生成表为准。
+
+配置文件缺失或损坏时回退到默认值，不会抛错。
+
+运行时产生的状态目录（都在 `<agent-dir>/proactive/` 下）：
+
+| 路径 | 内容 |
+| --- | --- |
+| `tasks.json` | 任务表（排期任务；每条记录带 `version:"v1"`，版本不识别的文件会被忽略并记日志） |
+| `agents/<agentId>.json` | 在线 agent 注册表（含心跳时间戳） |
+| `run/<agentId>.sock` | Unix domain socket 端点（同机实时通道） |
+| `mailbox/<agentId>/` | 文件邮箱（socket 不可用时的落盘兜底） |
+| `processed/<agentId>/` | 已处理信封与去重集合 `seen.json` 的归档位置 |
+| `mailbox/<agentId>/claimed/`、`expired/`、`corrupt/` | 认领中 / 过期 / 损坏信封的归档位置 |
+
+## 配置外置（提示词 / agent 定义）
+
+配置里**篇幅会长、要人工编辑**的内容（提示词、agent 角色说明、rubric、模板）改用独立文件维护，
+配置文件只留标量与引用。布尔开关 / 数字阈值 / 短枚举**不要**外置——那只会把「看一眼配置」变成「跳目录猜」。
+
+目录约定（相对 `config.json` 所在目录，即 `<agent-dir>/proactive/`）：
+
+```
+prompts/<ref>.md    # 提示词
+agents/<ref>.md     # agent 定义
+```
+
+引用写法：
+
+```json
+{
+  "idleTrigger": { "promptRef": "idle-probe" },
+  "contentRefs": { "reviewer": { "agentRef": "example-reviewer" } }
+}
+```
+
+- `promptRef` → `prompts/<ref>.md`；`agentRef` → `agents/<ref>.md`；
+- 文件可选带 front-matter（`---` 包裹的 `key: value` 块），其余部分是正文；
+- **优先级**：同层仍有内联 `prompt`（旧配置）时**内联优先**，并给一次性提示（ref 不生效）；
+- **失败即报错**：文件不存在 / 空文件 / 格式错 / 路径越界（`../`）→ 加载**失败并指名 ref 与路径**，
+  **不会**静默回退默认值；
+- 解析后的路径必须留在配置根目录内（越界路径与指向外部的符号链接都拒绝）；
+- 内容**单次读入快照**（外部程序同时改文件也不会读到半截内容）。
+
+示例：`pi-proactive/agents/example-reviewer.md` —— 复制到 `<agent-dir>/proactive/agents/` 后
+即可被上面的 `agentRef` 引用。
+
+> `<agent-dir>/proactive/agents/` 下同时存在**两种**东西：对端注册表 `agents/<agentId>.json`
+> 与外置 agent 定义 `agents/<ref>.md` —— 按扩展名区分，互不覆盖。
+
+---
+
+## 空闲判定基线（按实测修订）
+
+空闲判定现在用**「最近任何活动」**做基线：用户输入 **+ 代理活动**（模型回合起止 / 工具调用 / 助手消息落定）都会把计时归零。
+代理在干活时不再被当成「用户离开了」。
+
+- **两条基线**：`lastUserActivityAt`（**只有用户输入**刷新；`idleDetect` 三档的差异只决定用户输入是否计入）+
+  「最近任何活动」（判定用）。
+- **触发前必须确认代理已交回控制权**：回合进行中 / 工具链未结束时判定原因为「代理正在忙」，不触发。
+- **插件自己投递的主动消息不刷新任何基线** —— 否则插件会被自己的动作无限推迟下一次触发（自锁）。
+- **阈值维持 10 分钟**（`afterMs=600000`）+ 5 分钟冷却（`minGapMs=300000`）。
+
+**实测数字**（日志级测量；同一份会话日志数据集、同一 10 分钟阈值；来源：`pi-proactive/docs/idle-ground-truth.md`）：
+
+| 配置 | 工作期误触发率 | 漏报率 | 离开覆盖率 | 触发时机正确率 |
+| --- | --- | --- | --- | --- |
+| 旧基线（只算用户输入）+ 冷却 | 20.07% | 55.07% | 44.93% | 20.80% |
+| 新基线（任何事件都刷新）+ 冷却 + 忙碌门控 | **3.01%** | 68.77% | 31.23% | **73.31%** |
+
+**表述纪律**：在日志级测量下，工作期误触发率由 **20.07% 降到 3.01%**；这**不等于**「误触发率已消除」。
+
+**这份测量不能证明什么**（如实披露）：
+
+1. 不能证明「用户离开了」—— 只能证明「用户没有交互」；用户可能在读屏幕（与离开在日志里同形）。
+2. 不能证明某个阈值对某个用户 / 场景最优 —— 结论只在「单用户 · 重度 agentic 编码」场景内成立。
+3. 不能证明「打扰率 = 20.07%」等于用户被打扰的真实概率 —— 护栏、频率上限与投递成功率未建模。
+4. 不能证明新基线「一定更好」—— 漏报率从 55.07% 升到 68.77%（更少被叫醒，换更少打错时机）。
+5. 不能评估 `terminal` 档 —— 终端按键在会话日志里不可见。
+6. 不能替代真人实验 —— 这是日志级（实现级 / 测试级）证据，不是现场级证据。
+
+---
+
+## 能力边界与限制（如实披露）
+
+- **对端必须加载本插件**，跨会话 / 跨进程协作才成立。对方没装插件 → 消息永远不会被消费。
+- **跨机器只有落盘排队（~1s），没有实时通道。** 同机走 Unix socket 直连；跨机（共享目录 / NFS）
+  只能靠文件邮箱轮询，延迟约一个轮询周期（秒级），且不可靠（掉线、过期都可能导致消息不被处理）。
+- **对端正在流式输出时收到 reply，只会多出一个 turn（`turn_start`），不会多出一个新的 `agent_start`。**
+  reply 以 `deliverAs:"followUp"` 注入**同一个** agent run；对端**空闲**时收到 reply 才走 `triggerTurn:true` 起新 run，
+  那时才出现新的 `agent_start`。按「`agent_start` 计数」判定「被唤起了几轮」的监控 / 验收脚本会因此误判。
+- **跨会话 / 跨进程协作要求双方都加载本插件**。
+- **agentId = `<name>#<host>#<sessionId>`**（`name` = 工作目录 basename，`host` = 主机名，
+  `sessionId` = 宿主会话 id）：**会话稳定**（同一会话跨进程重启地址不变）、**会话间唯一**
+  （不同会话不会互相投递）。宿主未提供会话 id 时**退回 `<name>#<host>#<pid>`**（进程级唯一，
+  能力退化但不报错）；`PI_PROACTIVE_AGENT_ID` 可显式覆盖。
+- **离线投递**：对端**优雅退出** → 注册表**保留条目**并标 `offline` → 发送方**仍可解析**
+  → 消息**落盘到对方邮箱** → 对方**以同一 sessionId 重启后取回**。只有**从未注册过的纯名字**
+  才返回 `error`（无法确定邮箱目录，不得谎称已排队）。
+- **空闲触发默认关闭**（`idleTrigger.enabled=false`），不显式打开前不会打扰用户。
+- **残余限制（如实列出，不掩盖）**：
+  ① **达线程轮次上限的通知走 socket 优先 + 邮箱兜底** —— 离线请求方**也能收到**（落盘到其邮箱、待其上线后取回），但**不是实时**；去重粒度＝**(线程, 请求方)**（同一线程同一请求方只通知一次，不同请求方各自都被交代）；
+  ② **注入标记串会出现在模型可见正文与转录里**（用于精确识别「本插件自己注入的消息」，代价是正文多一串标记）；
+  ③ **旧的 `scope:"session"` 任务（无 `ownerSessionId`）在进程重启后不再匹配** —— 归属退回按 `ownerAgentId` 判定，而旧任务里的 `ownerAgentId` 是旧的 pid 形态、与当前的会话形态 agentId 不一致 → 这些旧任务不再被投递；
+  ④ **socket 路径过长会退化**（macOS 上限约 104 字符）→ 退化为文件邮箱落盘排队（延迟变大，功能不中断）；
+  ⑤ **注册表条目永不删除** —— 优雅退出只标 `offline` 不删文件 → `agents/` 目录会缓慢积压；
+  ⑥ **TUI 完整链路（提问 → 回答 → 回填）未验证** —— pty 档只做了部分场景抽验，完整链路未跑通（见 `docs/review/tui-smoke.md` 的 7 项未验证）；
+  ⑦ **跨家族独立复验未做**（本机只有 minimax 一个模型家族）；
+  ⑧ **跨机行为未验证**（仅落盘排队 ~1s）；
+  ⑨ **>10 分钟长时驻留未验证** —— 实测中每个宿主生命周期 ≤ 4 分钟，长驻下的资源 / 孤儿进程 / 内存行为未观测；
+  ⑩ **`every` 的小时级节拍未验证** —— 短时实测节拍正常，小时级是否漂移未观测；
+  ⑪ **默认 `/proactive idle on` 只切到 `input-only` 档** —— TUI 下**不订阅终端输入**（`attachTerminalInput` 只在 `terminal` 档调用）→ **敲键本身不刷新空闲基线**（基线只在宿主发出 `input` 事件时刷新）；需要按终端输入判定空闲，请把配置 `idleDetect` 设为 `terminal`；
+  ⑫ **定时投递可能因与主动触发共享冷却而被顺延（最多约 5 分钟）** —— 默认 `minGapMs=300000`（5 分钟），排期任务与主动触发共用同一个冷却闸门（`Guard.check()` 返回 `defer` → 任务的 `dueAt` 顺延）；需要准点投递请调小 `minGapMs`。
+- **威胁模型 = 同 UID 可信。** 同 UID 进程之间**没有认证**，信封里的 `from` 是自声明字段 ——
+  本插件**不是**安全边界，不要用它防御同机其它进程。
+- **护栏按 agent 作用域计数。** 每个 agent 进程各有一份护栏状态 ⇒ N 个 agent ⇒ N × 单 agent 上限，
+  不是全局上界。
+- **适用版本 pi 1.3.0。** 全部宿主 API 断言只对 `@earendil-works/pi-coding-agent` 1.3.0 验证过；
+  更高版本未验证。
+- **TUI 档 pty 仅抽验部分场景**（`docs/review/tui-smoke.md`：该报告自述不构成验收结论、并列 **7 项未验证**，其基线早于提问路径重写 → **需重跑才算数**）；rpc / json / print
+  等非交互模式的降级行为已实测。
+- **跨进程端到端实测（V-03）已完成**（`docs/review/cross-process-e2e.md`：两个真实 Pi 宿主 + 真实模型回合）。
+  ⚠️ 该基线**早于**「agentId 会话稳定化」与 M5c 修复轮 → **合并态已复测部分场景**（核心闭环与达上限通知，见 `docs/review/final-acceptance.md` §7.5/§8），**原 11 场景在合并态的逐条复测未做**。
+- **协作接线层（M5c）独立验收首轮判「不通过」**，修复轮已合入，**第三轮独立复验已出结论：有条件通过**（S-1~S-8 全关、P-1~P-7 全关；仍有 3 项 Minor 残余与若干未验证项，见 `docs/review/m5c-reverify-3.md`）
+  → 该层**不得**称已验收通过。
+- `/proactive on|off` **已落盘**（原子写 `<agent-dir>/proactive/config.json` 的 `enabled` 字段），**重启后仍生效**；`/proactive idle on|off` **不落盘**，仅当次进程内有效（重启后回到配置文件里的设置）。
+
+---
+
+## 排障
+
+先看插件日志（stderr，日志前缀 `[proactive]`），再看状态：`/proactive status` 会直接给出
+「为什么触发 / 为什么没触发」的判定说明。
+
+| 现象 | 排查方向 |
+| --- | --- |
+| **任务没触发** | ① `/proactive status` 看 `enabled` 是否为「已开启」——`off` 时定时投递与空闲触发**都不发生**；② 看「下次空闲触发 / 限制」行确认是否被冷却（`minGapMs`）、每小时上限（`maxPerHour`）、静默时段挡下；③ 确认任务在 `/proactive tasks` 里且 `enabled=true`；④ 任务归属是 `scope=session`，由**会话 id** 判定（会话 id 跨进程重启稳定）；若宿主未提供 session id，则退回按进程归属兜底 —— 这种情况下进程重启后旧任务不再归新进程所有 |
+| **消息一直 `queued`** | `queued` = **已落盘、尚未送达**，两种语义：① **对端离线待上线** —— 查 `<agent-dir>/proactive/mailbox/<对方 agentId>/` 是否有文件；对方**以同一 sessionId 重启**后会自动取回（agentId 会话稳定 → 邮箱路径不变）；若对端**从未注册过**（纯名字）则直接 `error`。② **对端在线但本轮未接收** —— 回执附原因（对端处理抛错 / 投递失败），消息同样落在对方邮箱待重试。两种都**不是**「已送达」 |
+| **空闲不触发** | ① 空闲触发默认是关的 → `/proactive idle on`（不落盘，仅当次进程内有效）或改配置 `idleTrigger.enabled=true`；② `idleDetect` 默认是 `off`，没有输入信号时不会猜你在不在 → 设成 `terminal`（仅 TUI）或 `input-only`；③ 非 TUI 模式下 `terminal` 会自动降级为 `input-only`；④ 确认不是「代理正在忙」（`busy`）或没到阈值（`threshold`） |
+| **对端找不到** | `message_agent` 的 `to` 按 **agentId 精确匹配 → 名字唯一匹配 → 前缀唯一匹配** 解析（同名 / 前缀命中多个会直接报错）；**离线条目同样可解析**（优雅退出保留条目并标 `offline`，心跳过期=崩溃也可解析）→ 消息落盘待其上线；只有**从未注册过的纯名字**才 `error`。注册表条目靠 30s 心跳刷新，超过 3 个心跳周期未刷新即视为离线 |
+| **socket 起不来** | 端点被占用（另一个进程还在）时会**降级为文件邮箱**并继续工作，日志里会有 `socket 通道启动失败（降级为文件邮箱）`；功能不中断，只是延迟变大 |
+
+团队级排障与看门狗告警语义见 `docs/team/WATCHDOG-RUNBOOK.md`（告警类别与处置责任人）、
+未验证项台账见 `docs/team/iteration-backlog.md`。
+
+---
+
+## 里程碑边界
+
+| 里程碑 | 内容 | 状态 |
+| --- | --- | --- |
+| M1 | 包骨架、`/proactive` 命令、工具接口、1s tick 与状态栏 | 已实现 |
+| M2 | 空闲触发、投递与护栏闭环 | 已实现 |
+| M3 | 任务落盘与调度 | 已实现 |
+| M4 | 跨进程协作（注册表 / socket / 邮箱 / 去重 / 接线） | 已实现（测试级验证）；V-03 核心闭环已合并态复测 |
+| M5 | 协作闭环（逐条 reply / 线程 / 轮次上限） | 已实现（测试级验证）；V-03 核心闭环已合并态复测 |
+| M6 | 分发与文档（README / 包元数据 / 版本约束） | 已实现 |
+| 跨进程端到端实测（V-03） | 两个真实 Pi 宿主跑通全链路 | **已完成**（`docs/review/cross-process-e2e.md`）；⚠️ 基线早于「agentId 会话稳定化」与 M5c 修复轮 → **合并态已复测部分场景**（核心闭环与达上限通知），**原 11 场景在合并态的逐条复测未做** |
+| TUI 交互语义 | 真人按键下验证主动提问 | **pty 仅抽验部分场景**（`docs/review/tui-smoke.md`；7 项未验证，基线早于提问路径重写，需重跑才算数） |
+| 跨家族独立复验 | 异族模型家族独立复审 | **未验证**（本机只有 minimax 一个模型家族） |
+| 跨机行为 | 两机 / NFS 实测 | **未验证**（仅落盘排队 ~1s） |
+| TUI 完整链路（提问→回答→回填） | pty 下的端到端提问闭环 | **未验证**（pty 档只抽验了部分场景；7 项未验证，需重跑才算数） |
+| 长时驻留（>10 分钟） | 长时间运行下的资源 / 孤儿进程 / 内存行为 | **未验证**（实测每个宿主生命周期 ≤ 4 分钟） |
+| `every` 小时级节拍 | 小时级运行下的节拍漂移是否累积 | **未验证**（短时实测节拍正常） |
+| 门禁 G11（文档↔实现一致性断言） | 机器化的文档↔实现一致性门禁 | **已存在**（判据在 `scripts/merge-gate.sh` 的 G11 段，默认零容忍；含**反向断言**：文档的否定式声明若指向仓库里已存在的对象 → 判为违规；回归自测在 `scripts/tests/gate-doc-consistency.test.sh`） |