pi-legion 3.0.3 → 4.0.0

package/docs/contracts/display-liveness-v1.md

@@ -0,0 +1,373 @@
+# 展示层活性判定统一契约 v1（FROZEN）
+
+> 状态：**FROZEN**（2026-10-24 用户裁决"直接第二步"）。
+> 冲突时**停下报告**，不得重新解释本契约。
+> 关联：#209-3（owner 判定）、#238（burst 合并 / KNOWN LIMITATION）、#266（queued 状态）。
+
+---
+
+## §1 问题陈述
+
+用户报告（原话）：
+
+> 轨道图上有还在处理的，就是还在处理，他没了就没了，不要说什么延迟什么的，
+> 我看起来就是时间没有对齐啊。
+
+现象（均已复现）：
+
+1. `subagent({action:"status"})` 显示 `Status · 1 live child`，同一个 child 又显示
+   `owner: dead (pid gone)` + `state=failed` —— **死掉的 child 被计入 live**。
+2. 后台通知说某 child `still running`，同时 `status all` 返回 `No live children`。
+3. `collect` 还能读出该 child 的完整报告（从 JSONL 历史重放）。
+4. 轨道图上某节点停在 `running`，而该子进程早已死亡。
+
+用户不接受"延迟投递"作为解释。**判定：用户的判断正确——这是时间语义错误，不是延迟。**
+
+---
+
+## §2 根因（已确证，带证据）
+
+### R1 — "活着"没有单一权威定义，散落在 3 类地方
+
+| 位置 | 判定方式 | 证据 |
+|---|---|---|
+| 列表筛选 | 只看 `child.state ∉ {retired, exited}` | `index.ts:3230` |
+| 文本渲染 | **额外**算 owner dead | `src/extension/runtime.ts:399-404` |
+| 轨道图 | `eventOverrides` + 账本行按时间戳竞选 | `src/extension/runtime.ts:702, 837-848` |
+
+后果：同一个 child 可以同时是 `live`（列表）和 `failed`（文本）和 `running`（轨道图）。
+
+### R2 — 跨写入方时钟被当作单调可比
+
+```ts
+// src/extension/runtime.ts:837
+if (node && event.ts >= node.updatedAt) {        // 第 1 道
+// src/extension/runtime.ts:839
+if (!previous || event.ts >= previous.ts) {      // 第 2 道
+// src/extension/runtime.ts:702
+if (override && override.ts >= node.updatedAt) { // 第 3 道
+  ...
+} else {
+  if (override) eventOverrides.delete(node.id);  // ← 永久删除 override
+  tree.set(node.id, { ...node });                // ← 采信账本行
+}
+```
+
+- `event.ts` 由**父进程**事件总线打时间戳。
+- `node.updatedAt` 由**子进程**写账本时打时间戳（`src/legion/nodes.ts:184`），
+  且**只在心跳时推进**：`src/extension/legion-tools.ts:145`
+  ```ts
+  const alive = children.filter((child) => this.supervisor.isAlive(child.name));
+  if (alive.length === 0) return;   // ← 死了就不写心跳
+```ts
+  **子进程一死，`updatedAt` 永久冻结。**
+
+**判定**：两个不同写入方的时钟**不构成全序**，用 `>=` 比较它们本身就不成立。
+第 3 道在 override 比账本行旧时**把 override 永久删除**，于是：
+
+> 一个已 `settled` 的节点，若账本行停在 `starting`（子进程死了），
+> 下一轮 `snapshotNodes()` 会删掉 settled override 并采信 `starting`
+> → **轨道图把已结束的节点拉回"还在跑"。**
+
+这正是用户看到的"没有对齐"。
+
+### R3 — 七个状态集合互不相同，且都不含 `queued`
+
+| 集合 | 定义位置 | 内容 |
+|---|---|---|
+| `RUNNING` | `src/tui/viz/model.ts:59` | starting, working, running, blocked |
+| `RUNNING_STATES` | `src/tui/status.ts:361` | starting, working, running |
+| `ACTIVE_STATES` | `src/tui/status.ts:362` | RUNNING_STATES + blocked |
+| `TERMINAL_STATES` | `src/tui/status.ts:363` | settled, success, completed, failed, aborted, retired, awaiting, unknown |
+| `ACTIVE_STATUSES` | `src/tui/tree-view.ts:20` | starting, running, blocked |
+| `TERMINAL_STATUSES` | `src/tui/tree-view.ts:21` | settled, failed, retired |
+| `LIVE_NODE_STATUSES` | `src/extension/legion-status.ts:43` | starting, running, blocked |
+| `LIVE_CHILD_STATUSES` | `src/legion/nodes.ts:25` | starting, running, blocked |
+
+`displayStatus()`（`src/tui/viz/model.ts:72-78`）的兜底是 `return "retired"`，所以：
+
+```
+displayStatus("idle")    === "retired"   ← idle 在轨道图上显示成"已退休"
+displayStatus("queued")  === "retired"   ← queued 显示成"已退休"
+displayStatus(undefined) === "retired"
+```ts
+
+### R4 — 孤儿检测只报告，不收敛
+
+```
+// src/extension/legion-tools.ts:251
+const event = appendEvent(this.db, node.id, "orphan_detected", {...});
+this.eventBus?.emit(event);
+this.sendRootMessage(`Legion orphan detected at ...`);
+// ← 没有 updateNode()：node.status 仍是 running
+```ts
+
+`orphanStaleMs` 默认 90s（`src/shared/types.ts:571`），但**只发消息不改状态**。
+启动期 `hygiene` 有 `node_abandoned` 路径（`src/runs/hygiene.ts`），但阈值是
+`staleNodeHours` 默认 **72 小时**，且只在启动时跑。
+
+### R5 — 已有代码承认过这个病，但选择了"让用户自己判断"
+
+`src/extension/legion-tools.ts:258-264` 的注释：
+
+> The notice can be delivered long after detection: it is queued through
+> `subagent-notify` and the outbox flushes at `MAX_PENDING_AGE_MS` or at
+> `agent_settled`. A stale `staleMs` alone therefore reads as "detected just
+> now" when the value can be tens of minutes old, which makes a replayed
+> notice look like a fresh detection. **Stamp the detection time so a late
+> delivery is self-evident.**
+
+**判定**：这是把时序缺陷转嫁给读者。v1 改为从根上消除，不再靠时间戳自证。
+
+### R6 — `#238` 的 KNOWN LIMITATION 与本契约的关系
+
+`test/unit/runtime.test.ts:3349` 明确钉住：
+
+> a mid-burst ledger write can make the painted status differ from a per-event re-read
+> ...
+> reproducing a SEQUENCE of reads is not possible with a constant number of reads,
+> which is why this is bounded and documented rather than fixed.
+
+**判定：该结论对本契约不构成障碍，因为本契约不试图"复现读取序列"。**
+它改变问题：**渲染不再是从事件序列累积出的状态，而是对"渲染时刻的事实"做一次纯投影。**
+同一时刻的事实只对应一个答案，故不存在序列依赖。
+该用例将改为断言"同一 facts 的任意读取次数得出一致结果"（见 A6）。
+
+---
+
+## §3 决策
+
+### D1 — 单一权威：`liveness()` 是唯一的"活着"判定
+
+新增纯函数模块 `src/extension/liveness.ts`（**无 fs / 无 db / 无 timer / 无 clock 读取**，
+所有输入由调用方传入）：
+
+```
+export type Liveness = "live" | "dead" | "unknown";
+
+export interface LivenessFacts {
+  /** 进程内注册表里是否存在且状态未终态。 */
+  readonly inMemory?: { readonly state: string } | undefined;
+  /** 账本行的状态与心跳时刻（可能来自已死进程）。 */
+  readonly ledger?: { readonly status: NodeStatus; readonly updatedAt: number } | undefined;
+  /** run.json 的 child 记录状态（调度层）。 */
+  readonly record?: { readonly state: string } | undefined;
+  /** pid marker 的存活判定结果；undefined = 没有 marker。 */
+  readonly pidAlive?: boolean | undefined;
+  readonly now: number;
+  readonly staleMs: number;
+}
+
+export function liveness(facts: LivenessFacts): Liveness;
+```ts
+
+**判定顺序（全序，不是"任一为真"）**：
+
+```
+1. inMemory 存在且非终态            → live    （最强：本进程正在持有它）
+2. inMemory 存在且是终态            → dead
+3. pidAlive === true               → live    （有进程真在跑）
+4. pidAlive === false              → dead    （进程确认已亡，D4 接受窗口）
+5. ledger 非终态 且 now - updatedAt < staleMs → live   （心跳未过期）
+6. ledger 非终态 且心跳已过期        → dead    （孤儿：D7 收敛）
+7. ledger 是终态                    → dead    （账本已落终态：已结束）
+8. record 是终态                    → dead    （调度层已判定结束）
+9. 其余（含全部 undefined）          → unknown （绝不猜）
+```
+
+**为什么是顺序而非并集**：并集会让"某处残留一条 running 账本行"永久压过
+"本进程已确认它死了"。顺序保证**更强的证据胜出**，且 `unknown` 是一个明确的
+第三态而非"当活处理"。
+
+### D1-a — 终态集合与未知标签（2026-10-24 父会话裁决）
+
+W1 实施时发现契约原文漏了两处，此处补全并冻结。
+
+**`TERMINAL_STATES`（账本/记录层终态）**
+
+```
+settled, success, completed, done,
+failed, aborted, error, truncated,
+retired
+```
+
+**`awaiting` 不是终态。** 它表示"活着但在等下游"
+（`src/runs/orchestrator.ts:2271`：`if (execution.status !== "running" && !isRetired()) child.state = "awaiting"`；
+`src/extension/recycle.ts:23` 也把它单列）。把它当终态，会让一个仍在等待的 centurion
+在展示层凭空消失。`awaiting` 归入**非终态**，展示为灰（同 `idle`，见 D5）。
+
+> `src/tui/status.ts:363-372` 现有的 `TERMINAL_STATES` 把 `awaiting` 当终态，且
+> `status.ts:525-528` 先把它改写成 `"waiting"` 再渲染。**W4 必须一并纠正**：
+> `awaiting` 既不消失，也不显示为终态。
+
+**未知标签：用补集，不用白名单。** 判定"非终态"用 `!isTerminalState(status)`，
+**不是** `NON_TERMINAL.has(status)`。认不出的标签不应让我们宣布其生命周期结束；
+白名单式判定会让 W2 传入真实账本行时静默掉进 `unknown`。
+`NON_TERMINAL` 仅作文档性导出，不参与判定。
+
+**`LivenessFacts.ledger.status` 用 `string`，不用 `NodeStatus`。**
+`idle`/`queued` 按 D9 永不进入 `NODE_STATUSES` 闭集，但 D5 要求它们是一等展示态；
+冻结成 `NodeStatus` 会迫使 W2/W4 处处 `as` 强转，反而模糊 D9 的边界。
+
+### D2 — 三态而非二态
+
+`unknown` 必须存在且**不得**被当作 `live` 展示。
+理由：把未知当活是当前 `status` 显示 `1 live child`（owner 已死）的直接原因；
+把未知当死会误杀正在启动的 child。第三态是唯一诚实的选项。
+
+### D3 — 跨写入方时钟不可比较（硬禁令）
+
+**禁止**在任何地方用 `>=`/`<=`/`>`/`<` 比较**来自不同写入方**的时间戳。
+
+具体：`event.ts`（父进程总线）与 `node.updatedAt`（子进程账本）之间的比较
+**全部删除**。事件只用于**触发重算**，不再用于**决定谁的结论胜出**。
+
+验收：`src/` 下不存在 `event.ts` 与 `updatedAt` 的直接比较。
+
+### D4 — pid 窗口接受（用户裁决 1）
+
+`pidAlive === false` 立即判 `dead`。不做心跳宽限、不加第二套时间语义。
+理由：pid 探测是最接近操作系统事实的判据；加宽限等于重新引入"时间没对齐"。
+
+已知窗口：进程刚退出、`isPidAlive` 尚未观察到的**秒级**窗口，接受。
+
+### D5 — `idle` 与 `queued` 是一等展示态（用户裁决 2）
+
+`displayStatus()` 的兜底 `retired` 必须拆开：
+
+| 输入 | 输出（`VizStatus`） | 展示 |
+|---|---|---|
+| `idle` | `idle`（新） | **灰**：`idle · 占槽待唤起` |
+| `queued` | `queued`（新） | `queued(n)` |
+| `starting` / `working` / `running` / `blocked` | `running` | 不变 |
+| `settled` / `success` / `completed` / `done` | `settled` | 不变 |
+| `failed` / `aborted` / `error` / `truncated` | `failed` | 不变 |
+| `retired` | `retired` | 不变 |
+| 其余 / undefined | `unknown`（新） | `unknown`，**不显示为 retired** |
+
+**为什么 `idle` 要显示而不是隐藏**：`idle` 的 child 仍然活着、仍占并发槽（F9），
+两个事实都要传达。标灰是"活着但没在干活"的准确表达。
+
+### D5-a — `LogEvent.kind` 不随 `VizStatus` 放宽（2026-10-24 父会话裁决）
+
+W4 实施时暴露一处契约未覆盖的连带影响，此处冻结。
+
+`src/tui/viz/panels.ts` 的 `LogEvent.kind` 是
+`"spawn" | "settled" | "failed" | "retired"`，`buildLog()` 原先把 `node.status`
+直接塞进去（`node.status !== "running"` 即视为结束）。`VizStatus` 放宽后这行必然报错。
+
+**裁决：`LogEvent.kind` 保持不变，`buildLog` 只对真正的结束态产生结束行。**
+
+```text
+结束态 = settled | failed | retired
+非结束态 = running | idle | queued | unknown   → 只有 spawn 行，没有结束行
+```
+
+理由：`idle`/`queued` 按 D5 **是活的**（占着槽，只是没在干活），`unknown` **未定**。
+把任何一项记成结束都会重新制造"活着的节点在 git-log 里已结束"的错误——
+与本契约要消灭的问题同类。`panels.ts` 归 **W4** 文件所有权。
+
+### D6 — 所有出口从 `liveness()` 派生
+
+以下出口**必须**调用 `liveness()`，不得自行判定：
+
+1. `subagent({action:"status"})` 列表筛选与头部计数（`index.ts:3223-3272`）
+2. `renderLiveChildStatus` 的 `state`/`owner` 行（`src/extension/runtime.ts:399-416`）
+3. `/legion` galaxy 全视图（`src/tui/viz/model.ts`）
+4. `/legion --tree` 与 paged tree（`src/tui/tree-view.ts`）
+5. `/legion status`（`src/extension/legion-status.ts`）
+6. 状态小部件 / strip（`src/tui/status.ts` 的 `filterLiveTree` / `isActiveEntry`）
+7. completion notice 投递前的终态复核（`src/extension/runtime.ts` 的 `flushOutbox`）
+
+**不再**允许出现局部的 `state !== "retired" && state !== "exited"` 式手写判定。
+
+### D7 — 孤儿必须收敛，不只是报告
+
+`scanOrphans` 命中（`legion-tools.ts:241-252`）时，除现有事件与消息外，
+**必须**把账本行收敛到终态：
+
+```
+updateNode(db, node.id, { status: "failed" }, timestamp);
+appendEvent(db, node.id, "node_abandoned", { reason: "no_active_supervisor", ... });
+
+理由：`orphan_detected` 只描述"发现了孤儿"，不改变事实；而用户要的是
+"他没了就没了"。收敛后 `liveness()` 的第 5 步自然给出 `dead`，无需任何展示层特判。
+
+**不得**复用 `hygiene` 的 72 小时阈值；孤儿判定阈值是 `orphanStaleMs`（默认 90s）。
+
+### D8 — 渲染是纯投影，不是事件重放
+
+`snapshotNodes()` / `refreshUi()` / `vizSnapshot()` 的语义改为：
+
+> 在时刻 T 读取一次事实（进程内注册表 + 账本 + run.json + pid），
+> 用 `liveness()` 投影出展示状态。
+
+`eventOverrides` 降级为**纯延迟优化**（事件到达时先乐观更新，减少一次读库），
+但**每次 `refreshUi()` 必须用事实校正**。校正规则：无条件以 `liveness()` 结果为准，
+**不做时间戳竞选**。
+
+### D9 — 保留 `NODE_STATUSES` 闭集
+
+`queued` / `idle` **仍然不得**进入 `src/legion/nodes.ts` 的 `NODE_STATUSES`
+（六值闭集，两条 SQL 硬编码六个 `?` 占位符）。它们是**展示态**，不是账本态。
+`test/unit/legion-nodes.test.ts` 的 A16 tripwire 保持不变。
+
+---
+
+## §4 实施切分
+
+| 单元 | 文件 | 内容 |
+|---|---|---|
+| **W1** | `src/extension/liveness.ts`（新） | D1 `liveness()` + D2 三态 + D5 状态映射表；纯函数，无 I/O |
+| **W2** | `src/extension/runtime.ts` | D3 删除三处时钟比较；D6 出口 2/5/7；D8 纯投影 |
+| **W3** | `index.ts` | D6 出口 1（`listLiveChildrenForStatus` + `renderStatusOverview`） |
+| **W4** | `src/tui/viz/model.ts`, `src/tui/viz/palette.ts`, `src/tui/viz/panels.ts`, `src/tui/status.ts`, `src/tui/tree-view.ts` | D5 新展示态 + D6 出口 3/4/5/6，集合归一 |
+| **W5** | `src/extension/legion-tools.ts` | D7 孤儿收敛 |
+| **W6** | `docs/`, `CHANGELOG.md` | 文档与迁移说明 |
+
+**文件归属（禁止越界）**：每个 W 只能改自己那一行的文件。
+`src/extension/liveness.ts` 由 W1 独占创建，其余 W 只读引用。
+
+---
+
+## §5 验收
+
+| 编号 | 断言 | 归属 |
+|---|---|---|
+| **A1** | `liveness()` 的 9 条判定顺序逐条覆盖；`unknown` 不被展示为 live | W1 |
+| **A2** | 已 `settled` 的节点，账本行冻在 `starting` 且心跳过期 → 渲染为终态，**不被拉回 running**（R2 回归） | W1+W2 |
+| **A3** | `owner: dead` 的 child **不计入** `Status · N live`（改正 `status-action.test.ts:301`） | W3 |
+| **A4** | `displayStatus("idle") === "idle"`、`("queued") === "queued"`、`("awaiting") === "awaiting"`、`(undefined) === "unknown"` | W4 |
+| **A5** | 孤儿超过 `orphanStaleMs` → 账本行变 `failed` + `node_abandoned` 事件；`liveness()` 随后给 `dead` | W5 |
+| **A6** | 同一组 facts 连续投影 100 次结果恒定（替代 `#238` KNOWN LIMITATION 的收敛断言） | W1+W2 |
+| **A7** | `src/` 中不存在 `event.ts` 与 `updatedAt` 的比较（D3 静态守卫） | W2 |
+| **A8** | `queued`/`idle` 未进入 `NODE_STATUSES`；A16 tripwire 仍绿 | W4 |
+| **A9** | `buildLog` 对 `idle`/`queued`/`unknown` 节点不产生结束行（D5-a） | W4 |
+
+---
+
+## §6 迁移影响（已知会打翻的既有断言）
+
+| 测试 | 现有断言 | 处置 |
+|---|---|---|
+| `test/unit/status-action.test.ts:301` | `/Status · 1 live child/`（死 child 算活） | **改为** `0 live` + 单独列出 dead |
+| `test/unit/status-action.test.ts:302-304` | `state=failed` + `owner: dead` | 保留文案，但不再计入 live |
+| `test/unit/runtime.test.ts:3349` | `#238` KNOWN LIMITATION「settled vs retired 分叉」 | **改为** A6 的收敛断言 |
+| `test/unit/legion-viz.test.ts:64-65` | `displayStatus("idle") === "retired"` | **改为** `=== "idle"` |
+| `test/unit/legion-status.test.ts`（12 条） | 逐行文本锁 | 逐条复核，`state=` 词表可能变 |
+| `test/unit/status.test.ts`（36 条） | 小部件清空/折叠 | 复核 `idle` 从"消失"变"标灰" |
+
+**要求**：每一处改动必须在 commit message 里写明"为什么旧断言是错的"，
+不得只改数字。
+
+---
+
+## §7 禁令
+
+1. **禁止**用时间戳比较决定展示状态（D3）。
+2. **禁止**把 `unknown` 当 `live` 或当 `dead` 处理（D2）。
+3. **禁止**给 pid 判定加心跳宽限或第二套时间语义（D4）。
+4. **禁止**把 `idle`/`queued` 塞进 `NODE_STATUSES` 闭集（D9）。
+5. **禁止**在展示层手写 `state !== "retired" && state !== "exited"` 式局部判定（D6）。
+6. **禁止**让 `orphan_detected` 只发消息不改状态（D7）。
+7. **禁止**在 `liveness.ts` 里读 `Date.now()` / fs / db / timer（D1 纯函数约束）。

package/docs/contracts/drop-non-pi-kinds-v4.md

@@ -0,0 +1,198 @@
+# 冻结契约：删除 cursor / 第三方后端支持，只保留 `kind: pi`（v4.0.0）
+
+状态：**FROZEN** — 实施中禁止偏离。发现矛盾立刻停下，报给父会话，**不要自行解释矛盾**。
+
+## 目标
+
+`pi-legion` 只支持 `kind: pi`。删除 (a) cursor 专属 kind 逻辑，(b) 归档 herdr 后端
+`src/backends/legacy/`，(c) 死掉的 `herdr.*` 设置与常量，(d) 一个派生缺陷（#233：未知事件
+类型冻结事件游标）。
+
+**不删除**：`spawnMode` 的 `rpc` / `inprocess` 两个 supervisory backend（那是 pi 的两种运行
+方式，与第三方后端无关）。任何声称「backend 也该删」的推论都是错的。
+
+## 已实测的硬事实（禁止重新侦察）
+
+本 worktree `npm ci` 已完成；基线在 HEAD `35edac5` 上实测：
+
+| 命令 | 结果 |
+|---|---|
+| `npm run typecheck` | exit 0 |
+| `npm test` | 1153 pass / 0 fail |
+| `npm run test:perf` | 17 pass / 0 fail |
+| `npm run test:integration` | 83 pass / 0 fail |
+| `npm run test:mock-llm` | 24 pass / 0 fail |
+
+删除规模（静态统计，非抽样）：
+
+| 触点 | 事实 |
+|---|---|
+| `src/backends/legacy/**` import 点 | 生产代码仅 `src/api.ts:21-30,341`；`index.ts` 零引用 |
+| `test/legacy/**` import 点 | `test/legacy/herdr-client.test.ts:12-15`、`test/legacy/cursor-chat.test.ts:13`、`test/legacy/helpers/fake-herdr.ts:16`、`test/unit/output-cap.test.ts:6` |
+| `test/unit/output-cap.test.ts` | **78 行 6 个 test，只有第 6 个（`legacy runner kills an infinite stream at the cap`）用 legacy runner**，其余 5 个测 `src/shared/output-cap.ts`。**禁止整文件删。** |
+| `AGENT_KINDS` 收敛后的破测面 | 15 个测试文件（见 D4 清单） |
+| `assertKindModelCoherent` 链 | `src/agents/presets.ts:167-183`（定义）+ `src/agents/step-model.ts:94-102`（唯一调用点） |
+| `nativeModelFor` 存活用途 | 仅 `src/runs/orchestrator.ts:844`，且**永久传 `"pi"`**；等价于 `applyThinkingSuffix`（`src/runs/args.ts`） |
+| `herdrStatus` 生产写入点 | **0**。`src/tui/status.ts` 内 8 处全读，`test/unit/status.test.ts:296` 是唯一写入者（测试造数） |
+| `run.herdr` 字段 | **活跃字段**：写入点 `index.ts:421,464,1701,2294`、`src/runs/orchestrator.ts:707`、`src/runs/store.ts:256,277`，承载 `{supervisor, node_id}`。**禁止删字段** |
+| `DEFAULTS` 7 个 herdr 键 | `startRetries`/`startRetryBackoffMs`/`maxConcurrentAgents`/`sessionRetentionDays`/`startTimeoutMs`/`binaryProbeTimeoutMs` 全仓 **0 引用**；`commandTimeoutMs` 仅在 `src/backends/legacy/client.ts` 用 |
+| 用户可见的 `herdr` 字面量 | `src/extension/playbook.ts:19`（"using herdr pane/tab/agent commands"）、`src/tui/status.ts:555`（`● Async agents · herdr`） |
+| CHANGELOG 锚点 | `CHANGELOG.md:439` 指向 `README.md#herdr-transition-and-role-migration` → 改 README 章节标题必须同步改它 |
+
+## 决策（D 编号）
+
+**D1 — 兼容性策略：硬删，但「被忽略的角色/预设字段」要响一次。**
+- `AGENT_KINDS` 收敛为 `["pi"]`。**`AgentKind` 类型保留**（值域收窄），`AgentConfig.kind` 字段保留
+  （大量 plumbing 依赖它，删字段是另一场改动）。
+- 用户角色卡里的 `kind: cursor` 等：`parseAgentDocument` 保持 `enumOr` 语义（fallback `"pi"`），
+  **但**当 frontmatter 显式写了 `kind` 且不在合法集内时，`console.error` 一次，含角色名、原值、
+  以及「v4 只支持 kind: pi，该字段被忽略（按 pi 启动）」。同样的响一次也用于
+  `subagents.presets.<name>.kind` 与 `agentOverrides.<name>.kind`（这三处是用户唯一能写 kind 的入口）。
+- **不做**旧前缀别名（`kimi/k2` → `cb/kimi-k2` 之类）。模型名不在本契约范围。
+
+**D2 — 删 `cursorModel` 与整条 kind 分支，`nativeModelFor` 直接消失。**
+- `src/runs/kind.ts` 整文件删除（`planKindStart` 生产调用者为 0，见上表）。
+  `nativeModelFor` / `isPiShapedModel` / `cursorModel` / `planKindStart` 全部删除。
+- `src/runs/orchestrator.ts:844` 改为 `applyThinkingSuffix(model, thinking)`；
+  `dropped` / `modelDropped` / `ChildRecord.modelDropped`（`src/shared/types.ts:366`）与
+  `index.ts:1993-1997` 的「runs on X's own default」提示全部删除 —— 现在不存在「pi 表达不了的模型」
+  这类情形，只有「没设置模型」。
+- `applyThinkingSuffix` 的语义差异必须验证：`nativeModelFor("pi", m, t)` ===
+  `applyThinkingSuffix(m, t)`（`applyThinkingSuffix` 的 `replaceExisting` 默认 `false` 与 `nativeModelFor`
+  一致）。**在删 `nativeModelFor` 之前先写一条等价断言**（D8 覆盖）。
+- `assertKindModelCoherent` 与 `src/agents/step-model.ts` 的调用点一并删除（它的唯一用途是
+  「模型的 kind 与 preset 的 kind 不一致时拒绝」，kind 只有 pi 之后不存在不一致）。`PresetConfig.kind`
+  字段保留但只接受 `"pi"`（由 D1 的响一次覆盖非 pi 值）。
+
+**D3 — 删 `src/backends/legacy/**` 与 `test/legacy/**`。**
+- `src/api.ts`：删 `:19-30`（deprecated herdr transport 段）、`:329-341`（legacy types 段）、
+  `:194-200` 里的 `cursorModel`/`nativeModelFor`/`planKindStart`/`KindStartPlan`/`isPiShapedModel`。
+- `test/unit/api.test.ts:9` 的 `createHerdrClient` 断言删除（**不是**改成 false，直接删这一行），
+  其余 4 条断言保留。
+- `test/unit/output-cap.test.ts`：只删 `:6` 的 import 与第 6 个 test（`:57-63` 附近），其余 5 个保留。
+- `tsconfig.json:18` 的 `include` 覆盖 `test/**/*.ts`，所以 `test/legacy` 的删除必须与
+  `src/backends` 的删除**同一个 commit**，否则 typecheck 必红。
+- `package.json:56` 的 `test:docker` echo 文案里的 legacy 措辞改为中性（只改文案，命令不变）。
+
+**D4 — `AGENT_KINDS` 收敛会打红 15 个测试文件，必须同批修复。**
+完整清单（`rg -c` 实测命中数）：
+`test/unit/step-model.test.ts`、`test/unit/presets.test.ts`、`test/unit/kind.test.ts`（整文件删）、
+`test/unit/agents-listing.test.ts`、`test/unit/teams.test.ts`、`test/unit/status.test.ts`、
+`test/unit/summary.test.ts`、`test/unit/agents.test.ts`、`test/unit/inprocess-supervisor.test.ts`、
+`test/unit/context-injection.test.ts`（`planKindStart` 相关 2 个 test 删）、
+`test/unit/presets-regression.test.ts`、`test/unit/notify.test.ts`、
+`test/integration/orchestrator.test.ts`、`test/unit/agents-model.test.ts`、`test/unit/provider-pin.test.ts`。
+- 非 pi kind 的 test 用例**直接删除**，不要改成 `assert.throws`（拒绝逻辑本身也不存在了）。
+- `test/unit/agents-listing.test.ts:377,393` 的 `cannot be used with kind 'cursor'` /
+  `dropped at launch: kind 'cursor' runs on its own default` 断言删除（`src/extension/slash.ts:279-292`
+  的整段提示随 D2 一起删）。
+
+**D5 — 删死掉的 `herdr.*` 设置面（保留 `run.herdr` 字段）。**
+- 删：`src/agents/settings.ts:14`（import）、`:91-92`、`parseHerdrSettings` 全函数（`:119-185`）、
+  `:480-481` 调用、`:817` 注释里的 `herdr`、`:866-868` 合并；
+  `src/shared/types.ts` 的 `HerdrSettings`（`:519-533`）、`SubagentsSettings.herdr`（`:702-703`）、
+  `DEFAULTS` 里 7 个 herdr 键（`:790-807`，改造后 `DEFAULTS` 只剩 `turnTimeoutMs`/`settleQuietMs`）、
+  `ErrorCodes.HERDR_UNAVAILABLE`（`:769`）与 `ErrorCodes.PANE_BUSY`（`:772`）。
+- **`RunRecord.herdr`（`types.ts:382-388`）保留原名不删**（活跃字段，改名是另一场改动）。
+- 旧 settings 文件里残留 `subagents.herdr` 时：`parseHerdrSettings` 被删后该键**静默丢弃**
+  （与 `parseInProcessLimits` 的「未知键忽略」一致）。**这是可接受的**，因为该块自 2.0.0 起已被忽略、
+  且当前会打 deprecation 警告——警告随解析器一起消失。契约声明：**不做**新的「未知键报警」机制。
+
+**D6 — 用户可见的 `herdr` 措辞清理。**
+- `src/tui/status.ts:555` 的 widget 标题 `● Async agents · herdr` → `● Async agents`。
+  **同步改 `test/unit/status.test.ts:195` 的断言**（这是硬编码字面量）。
+- `src/extension/playbook.ts:19`：「using herdr pane/tab/agent commands for dispatch」→
+  「launching child Pi processes by hand (use the subagent tool)」。该字符串会进 LLM 上下文，措辞要准。
+- `src/extension/summary.ts:620` 的 `run.herdr.supervisor ?? "legacy"` → `?? "unknown"`。
+- `herdrStatus` 字段（`src/tui/status.ts:36` 及 8 处读）**保留不删**：它是 `StatusEntry` 的
+  `Pick<>` 成员，且 `test/unit/status.test.ts:296` 造数依赖；改名是另一场改动。
+
+**D7 — #233：事件类型闭集 + 轮询容错，两件事都做。**
+- (a) `node_abandoned` 加入 `src/legion/events.ts` 的 `LEGION_EVENT_TYPES`（现 14 → 15 项）。
+  同步 `test/unit/legion-events.test.ts:20` 的 `assert.equal(LEGION_EVENT_TYPES.length, 14)`。
+  `src/runs/hygiene.ts:275` 的 `RETAINED_EVENT_TYPES` 已含它，不动。
+- (b) `src/extension/event-bus.ts` 的 `poll()` 容错：**一条毒行不得冻结游标**。要求：
+  - `readEventsAfter` 抛出「未知类型 / 数据 JSON 损坏」这类**单行**错误时，游标**越过该行**并继续，
+    `onError` 照常被调用（每个毒行报一次，不重复刷屏）。
+  - 实现方式由 worker 定，但必须满足可验证性：★verifier 用真实 SQLite 造 3 行
+    （`node_launched` / `node_abandoned` 快照行 / `phase_change`），断言
+    `delivered === 2`、`cursor === 3`、`errors.length === 1`；
+    再 poll 一次，断言 `errors.length` 仍为 1（不重复报）、`cursor === 3`（不自旋）。
+  - **不要**改 `readEventsAfter` 的签名或让它静默吞错：`readEventsAfter` 的严格性（`test/unit/legion-events.test.ts`
+    的 `assert.throws(appendEvent(..., "unknown" as never))`）必须保留。容错只发生在 poller。
+  - **不要**在 `LegionEventBus.emit` 路径上加容错：那是进程内事件，类型由 TS 保证。
+
+**D8 — #233 的回归测试要「翻转」，不要「删掉」。**
+- `test/perf/event-bus.test.ts` 的最后一个 test（标题含 `REGRESSION (open defect)`）：
+  标题改成不带 open-defect 的表述，断言翻转为「毒行之后的合法事件仍然送达」。
+- 另在 `test/unit/legion-event-bus.test.ts` 增加一条**非 perf** 的容错回归（perf 套件不在 CI 里跑，
+  这条必须进 CI）。可用 `makeClock()` 现有的假时钟模式。
+- D2 的 `nativeModelFor("pi") === applyThinkingSuffix` 等价断言，加在删除 `nativeModelFor` **之前**跑一次
+  即可（不要求留在仓库里）。
+
+**D9 — 文档面最小改动，历史文档不重写。**
+- **改（产品面，5 处）**：
+  1. `README.md:87-89` —— 删「`kind !== "pi"` 会被拒」的整句。顺手修掉同段的悬空引用
+     「see Isolation below」（README 无 `## Isolation` 标题）。**不要**改 `README.md:217` 的
+     `legion_mail({ ..., kind? })`（邮件 kind，同名不同物）。
+  2. `README.md:508-528` —— 章节标题改为 `## Supported kinds`（**保留** `herdr` 历史交代的正文），
+     同步 `README.md:33` 的 Contents 项与 `CHANGELOG.md:439` 的锚点。整节重写为：
+     「v4 只有 `kind: pi`；`kind` 仍是合法 frontmatter 键但只接受 `pi`；非 pi 值被忽略并按 pi 启动」。
+  3. `docs/inprocess-supervisor.md:14`（fallback 触发条件去掉 non-pi）与 `:190-192`（Refusals 里的
+     non-pi 条目删除）。
+  4. `skills/pi-legion/SKILL.md:85-87` —— 这是**运行期注入 agent prompt 的文本**，优先级最高：
+     把「Pi Legion v2 supports `kind: pi`; for a role that requires a non-Pi CLI, use the Herdr-era
+     0.16.x release line」改成「Pi Legion runs `kind: pi` roles only」之类的现行表述。
+  5. `CONTRIBUTING.md:110-113`（deprecated herdr 导出段）与 `:164-175`（Legacy Herdr / kind checks 段）：
+     前者的 helper 已删，整段重写；后者指向已删的 `test/legacy/docker/verify-13-kinds.sh`，整段删除。
+- **不改（历史设计文档）**：`docs/design.md`、`docs/legion-v2-contract.md`（除 §15 追加一条 REV）、
+  `docs/legion-v2-delivery.md`、`docs/tui-viewer-contract.md`、`docs/contracts/spawn-default-inprocess-v3.md`、
+  `docs/contracts/osc-busy-plugin.md`、`docs/performance-2026-10-19.md`。
+  在 `docs/legion-v2-contract.md` 的 REV 表（`:448-460`）**追加一行** REV-13：`v4 收紧为仅 kind: pi；
+  AGENT_KINDS 收敛为 ["pi"]；非 pi 值忽略并按 pi 启动`。
+- **假阳性白名单（禁止改动）**：`docs/tui-viewer-contract.md` 的 `cursor`/`kind:` 全是文件游标与
+  ChatItem 判别式；`docs/performance-2026-10-19.md` 的 `cursor` 全是事件游标；
+  `docs/legion-v2-contract.md:173,313,355` 是邮件 kind；`docs/design.md:416` 是 artifact kind。
+
+**D10 — 版本与 CHANGELOG。**
+- `package.json` version → `4.0.0`，`package-lock.json:3,9` 同步（`npm install --package-lock-only`）。
+- `CHANGELOG.md`：`## [Unreleased]` 下写成 `## [4.0.0] — 2026-10-19`，用既有 `### Breaking` 标题
+  （唯一先例在 `CHANGELOG.md:379`），并补 `[4.0.0]:` 链接定义。
+- **不推 tag、不发版**。发版由父会话在 review 通过后决定。
+
+## 文件所有权（并行 writer 之间）
+
+- **T1 writer（events，#233）**：`src/legion/events.ts`、`src/extension/event-bus.ts`、
+  `test/unit/legion-events.test.ts`、`test/unit/legion-event-bus.test.ts`、`test/perf/event-bus.test.ts`。
+  禁止触碰其它文件。
+- **T2 writer（kind/backend 删除）**：`src/shared/types.ts`、`src/api.ts`、`src/runs/kind.ts`（删）、
+  `src/runs/orchestrator.ts`、`src/agents/{agents,presets,step-model,settings,overrides}.ts`、
+  `src/extension/{slash,summary,playbook}.ts`、`src/tui/status.ts`、`src/backends/**`（删）、
+  `test/legacy/**`（删）、`test/unit/*`（除 T1 的四个文件）、`test/integration/orchestrator.test.ts`、
+  `tsconfig.json`（不改内容，仅确认 include 仍成立）、`package.json:56` 文案。
+  禁止触碰 `src/legion/**` 与 `src/extension/event-bus.ts`。
+- **T3 writer（文档 + 版本）**：`README.md`、`docs/inprocess-supervisor.md`、`docs/legion-v2-contract.md`
+  （仅 REV 表追加一行）、`skills/pi-legion/SKILL.md`、`CONTRIBUTING.md`、`CHANGELOG.md`、
+  `package.json`（仅 version）、`package-lock.json`。
+  禁止触碰 `src/**` 与 `test/**`。
+- 三个 writer 的改动集**不相交**。T1 与 T2 都碰 `test/unit/`，但文件不重叠；T2 的清单里已显式排除 T1 的四个文件。
+
+## 验收（每个 writer 的 verify，由父会话在本 worktree 执行）
+
+T1：`npm run typecheck` && `npm test` && `npm run test:perf`
+T2：`npm run typecheck` && `npm test` && `npm run test:integration` && `npm run test:mock-llm`
+T3：`npm run typecheck`（文档不改代码，这道只保证 package.json 改动没打断类型检查）+ 父会话人工读改后的文档段。
+
+**全绿判据**：`npm run typecheck` exit 0；`npm test` 0 fail；`npm run test:integration` 0 fail；
+`npm run test:mock-llm` 0 fail；`npm run test:perf` 0 fail。用例总数会下降（删测试），
+**只允许因删除非 pi kind 用例而下降，任何断言级失败都是 rejected**。
+
+## 明确不做（防止越界返工）
+
+1. **不删** `spawnMode` 的 `rpc`/`inprocess`，不删 `RoutingSupervisor`。
+2. **不删** `AgentConfig.kind` 字段、`LegionNode.kind` 列、`RunRecord.herdr`、`StatusEntry.herdrStatus`。
+3. **不删** `LEGACY_EXTRA_AGENT_DIRS_ENV`（`PI_HERDR_SUBAGENTS_EXTRA_AGENT_DIRS` 别名）——
+   与 kind 无关，见 README:456 的「至少保留一个 minor」承诺。
+4. **不改** `docs/design.md` 等历史文档的既有正文。
+5. **不改** `readEventsAfter` / `appendEvent` 的签名与严格性。
+6. **不推** tag、不发 npm。

package/docs/contracts/esc-abort-v1.md

@@ -23,7 +23,7 @@
 |---|---|---|
 | R1 | `index.ts:613` 工具 execute 把 signal 参数命名 `_signal` 直接丢弃，全仓无 AbortSignal 处理 | scout-0 |
 | R2 | pi 核心 abort 只在批次边界检查 signal，不强杀 in-flight tool promise，等它自然 resolve | scout-1 |
-| R3 | `Orchestrator.collect` 内部 deadline 续期（COLLECT_GRACE_EXTENSIONS=2）+ waitForQuiet（2.5s 安静窗口轮询）+ applyVerification（600s cap）使 collect 实际可等 3×timeoutMs+600s | scout-0 |
+| R3 | `Orchestrator.collect` 内部 deadline 续期（COLLECT_GRACE_EXTENSIONS=2）+ 轮询等待点（2.5s 安静窗口 `waitForQuiet`，已由 #232 / PR #244 删除；现存 `waitOutTransientConnection` + `collectArtifactGrowing`）+ applyVerification（600s cap）使 collect 实际可等 3×timeoutMs+600s | scout-0 |
 | R4 | 无显式 stop 命令，LLM 只能逐个 retire | scout-0 |
 
 ## 冻结决定
@@ -68,7 +68,7 @@ async execute(_id, params, signal, onUpdate, ctx) {
 
 - 三个可中断等待点全部接 signal：
   1. `awaitSupervisor` 内 `supervisor.waitSettled(...)` → supervisor 层新增可选 signal 参数：`waitSettled(name, timeoutMs, signal?)`，在 signal abort 时同步 resolve `{ settled:false, abnormal:false, reason:"aborted by parent" }` 并清 timer（`resolveWaiters` 已有清 timer 逻辑，需给单 waiter 提前退出路径——最简单：waiter 注册时若 signal 存在则挂 listener，abort 时从 child.waiters 删除自己 + clearTimeout + resolve）。
-  2. `waitForQuiet` 轮询循环：每轮检查 `signal?.aborted` → return。
+  2. `waitOutTransientConnection` / `collectArtifactGrowing` 轮询循环：每轮检查 `signal?.aborted` → return。（原文写作 `waitForQuiet`；该方法已由 #232 / PR #244 删除，`signal` 语义不变，仍覆盖 collect 内两个轮询等待点。）
   3. `applyVerification`：`RunVerifyRunner.verify(...)` 若不支持 signal，则在 `finishCollect` 前后不做额外处理（保持现状），但 collect 整体 deadline 检查点加 `signal?.aborted` 短路。
 - `waitSettled` 的 signal 参数是**可选**追加参数，向后兼容（默认 undefined 行为不变）——已有调用点不传即不变。
 
@@ -98,7 +98,7 @@ subagent({action:"stop", all: true})          // 全部 live children
 |---|---|---|
 | index.ts | execute signal 接线、waitAction signal 透传、stop action、TOOL_DESCRIPTION | worker |
 | src/extension/runtime.ts | waitOne signal 臂、WaitResult.interrupted、renderWait、wait opts.signal | worker |
-| src/runs/orchestrator.ts | collect opts.signal、waitForQuiet/awaitSupervisor 短路 | worker |
+| src/runs/orchestrator.ts | collect opts.signal、轮询等待点/awaitSupervisor 短路 | worker |
 | src/supervisor/rpc-supervisor.ts | waitSettled 可选 signal 参数 | worker |
 | src/supervisor/types.ts | LegionSupervisor 接口 waitSettled 签名（如有） | worker |
 | src/extension/playbook.ts | TOOL_DESCRIPTION / PARENT_PLAYBOOK 同步 stop + wait 说明 | worker |
@@ -126,7 +126,7 @@ subagent({action:"stop", all: true})          // 全部 live children
 - index.ts:595-935（execute、controlAction、launchFamily 分派）
 - index.ts:1765-1810（waitAction）
 - runtime.ts:440-547（ensureCollect/waitOne）、831-838（wait）
-- orchestrator.ts:769-941（collect/awaitSupervisor/waitForQuiet/retire）
+- orchestrator.ts:769-941（collect/awaitSupervisor/轮询等待点/retire；原 `waitForQuiet` 已由 #232 / PR #244 删除）
 - rpc-supervisor.ts:353-396（waitSettled/isAlive）、760-838（retireChild）
 - 4 个单测锚点：`test/unit/supervisor.test.ts:295` 等现有 waitSettled 测试不变（可选第三参数不破坏旧签名）。
 - `waitSettled` 当前在 `src/supervisor/types.ts:81` 接口里，改为 `waitSettled(name: string, timeoutMs?: number, signal?: AbortSignal): Promise<SettleResult>`；唯一非测试调用点 `orchestrator.ts:800`。

package/docs/contracts/esc-no-retire-v3.md

@@ -33,14 +33,14 @@ interrupted (parent turn ended; children still running)
 
 ### D. TUI 提示
 
-有 live child 时，aboveEditor 状态栏常驻 `/legion stop [name|all]`（短版 `/legion stop`）：railway header 在宽度挤压下可截断摘要以保短 hint；`PI_LEGION_STRIP=tree` 在 header 下另起一行短提示。无 idle 门控。
+有 live child 时，aboveEditor 状态栏常驻 `/legion stop [--force] [name|all]`（短版 `/legion stop`）：railway header 在宽度挤压下可截断摘要以保短 hint；`PI_LEGION_STRIP=tree` 在 header 下另起一行短提示。无 idle 门控。
 
 ## 语义边界
 
 | 动作 | children |
 |---|---|
 | Esc 打断 wait / 父 turn | 继续跑；re-arm watch；settle 通知 |
-| `/legion stop` / `stop` action | graceful retire |
+| `/legion stop` / `stop` action | graceful retire; `--force` / `force:true` → hard retire |
 | 主进程退出 / session_shutdown | drain（print/json）+ retire |
 | SIGINT | 进程退出 → retire |