pi-legion 0.16.0 → 2.0.0

package/docs/contracts/esc-cascade-v2.md

@@ -0,0 +1,100 @@
+# ESC 级联关闭契约（v2，2026-10-13 冻结）
+
+## 背景
+
+v1（esc-abort-v1.md，已随 e66c85f 合入）冻结了「ESC ≠ 杀 children」语义。用户裁决推翻：turn 是 children 的 owner，turn 被 abort 时 children 应级联关闭，否则是资源泄漏。
+
+## 冻结决定
+
+### A. ESC 打断 turn → 级联优雅关闭 children
+
+改动点 `index.ts` 工具 execute（约 :687-691 的 `signal?.aborted` 快速返回处）：
+
+```ts
+if (signal?.aborted && action !== "stop") {
+    // NEW: cascade-close children owned by this turn before returning.
+    await cascadeRetireAll();   // fire-and-forget 也可以，但要保证 promise 存活到 retire 完成
+    return ok("interrupted (parent turn aborted)");
+}
+```
+
+**注意**：进入 execute 时 signal 已 aborted 的情况（ESC 发生在此工具调用排队后、执行前）——此时本 turn 尚未 launch 过任何 child，cascade 是 no-op，安全。
+
+但真正的触发点是**执行中途 abort**：wait/collect 正在 await 时 signal 才 abort。这些路径已有 interrupted 返回分支（waitAction / collectChild / collectInline / waitOne），在这些分支统一调 `cascadeRetireAll()`。
+
+### B. cascadeRetireAll 实现（index.ts）
+
+```ts
+const cascadeRetireAll = async (): Promise<void> => {
+    // 1. runtime 跟踪的所有 jobs（与 stopAction all:true 相同的目标集）
+    for (const name of targets) runtime.cancelWatch(name);   // 先停 watch，防 retire 期间通知噪音
+    await Promise.all([...jobs.map((job) => job.retire?.()), ...pendingUtilityRetires]);  // 全部 best-effort catch
+    // 2. release 全部
+};
+```
+
+复用 stopAction 的骨架但**不生成工具结果文案**（不是用户显式 stop，静默级联）。vexillatio 的 pendingUtilityRetires 一并级联。
+
+### C. wait/collect 中断路径统一接线
+
+所有「signal aborted → return interrupted」的分支（index.ts waitAction 间接层 + runtime.waitOne + collectChild + collectInline + launchFamily abandoned 路径）在返回前触发 cascade（一次性，防重入——用 module-level `cascading` promise 去重即可，同一 signal 只触发一次）。
+
+**防重入**：同一 abort 事件可能同时命中多个 in-flight 工具调用（parallel tool calls），cascade 必须幂等：用 `let cascadePromise: Promise<void> | undefined` 缓存，已存在则复用。turn_start 时重置（新 turn 新级联）。
+
+### D. vexillatio collect 接 signal
+
+`index.ts` launchUtilityFamily（约 :1895）：
+```ts
+const result = await handle.orchestrator.collect(handle.name, { timeoutMs, ...(signal ? { signal } : {}) });
+```
+vexillatio 工具 execute 也要把 signal 传进来（找到它的 registerTool 调用，第 3 参数接上）。ESC 后 utility children 也应被 retire（它们进了 pendingUtilityRetires，cascade 覆盖）。
+
+### E. 契约/文档更新
+
+- docs/contracts/esc-abort-v1.md：顶部加「v2 修订：ESC 语义改为级联关闭，推翻 v1 的『ESC ≠ 杀 children』」——保留原文供考古，加修订记录。
+- docs/design.md、README.md、playbook（TOOL_DESCRIPTION / PARENT_PLAYBOOK）相应语句更新：ESC abort 会级联 retire children；wait 被打断时 children 一并关闭。
+
+## 语义边界（不变）
+
+- **stop action 不变**：显式停止仍走全链。
+- **主 pi 正常退出（quit）不变**：session_shutdown 已级联。
+- **SIGKILL/崩溃不覆盖**：孤儿扫描 + resume 语义不变（这是既定接受的风险）。
+- **children 的 children**：retire 链本身递归（孙进程 sweep 在 rpc-supervisor 的 retireChild 里），无需额外处理。
+- **blocked children**：一并 retire（stop 语义一致）。
+
+## 文件归属
+
+| 文件 | 改动 |
+|---|---|
+| index.ts | cascadeRetireAll + 各中断分支接线 + vexillatio signal |
+| src/extension/playbook.ts | TOOL_DESCRIPTION / PARENT_PLAYBOOK 更新 |
+| docs/contracts/esc-abort-v1.md | v2 修订记录 |
+| docs/design.md, README.md | 语义说明 |
+| test/unit/* | 新测试 |
+
+## v2.1 修订（2026-10-13，会话 01a13345 实测后补）
+
+v2 的触发点只覆盖了「abort 落在 in-flight subagent 工具调用上」（wait/collect/launch 中途）。**async launch（默认形态）在 ESC 前就早已返回**：ESC 落在模型生成、空档或别的工具上时，没有任何 subagent 工具在执行，signal 无处投递，级联不触发——子 agent 继续跑，直到 session_shutdown 或显式 stop。
+
+实测：2026-10-13 03:20Z 会话 01a13345 async 启动 centurion（worktree），03:20:10 ESC abort 父 turn，子 agent 存活至用户退出父会话（03:20:24，走的是 session_shutdown 级联）。
+
+**修复**：`index.ts` 注册 `pi.on("agent_settled")`——pi 核心在每个 agent run 结算时发 `{ aborted: boolean }`，ESC abort 后必为 true（见 pi AgentSettledEvent："Whether the run ended because it was aborted, for example with Escape."）。handler 在 `event.aborted` 时 fire-and-forget `cascadeRetireAll()`（不 await：优雅 retire 可达秒级，不能拖住 settle 路径）。注册点与 turn_start 相邻、位于子进程 early-return 之前，父会话/嵌套子/工具人全部生效；无 runtime 的会话上是 no-op。幂等性由既有 cascadePromise/cascadingJobs 保证：ESC 打断 in-flight 工具时工具路径先触发一次，agent_settled 再触发一次为 no-op。
+
+## 验收
+
+1. typecheck + unit + integration 全绿。
+2. 新测试：wait 中途 abort → children 被 retire（mock 验证 retire 调用 + cancelWatch + release）。
+3. 新测试：cascade 幂等（同 signal 两次触发只 retire 一次）。
+4. 新测试：parallel 工具调用同时 abort，cascade 只跑一次。
+5. 新测试：vexillatio collect 在 abort 时提前返回（不长等 600s）。
+6. 新测试（v2.1）：async launch 已返回后 emitSettled(true) → 子 agent 被 retire、无完成通知。
+7. 新测试（v2.1）：emitSettled(false)（正常结算）→ 不 retire，async 子继续运行。
+
+## 锚点（以 master bc9c205 为准）
+
+- index.ts:687-691（execute 入口 aborted 快速返回）
+- index.ts:832-840（session_shutdown 参考——cascade 参考其形状）
+- index.ts:2243-2280（stopAction 骨架——cascade 复用）
+- index.ts:1890-1900（vexillatio collect）
+- runtime.ts:481-590（waitOne interrupted 分支）
+- master 上无 worktree 依赖，直接在主 repo 改。

package/docs/design.md

@@ -584,7 +584,7 @@ preset 规则：
   （`src/agents/step-model.ts`），只在该步骤确实引用了 preset 时生效
 - **响亮失败**：引用了未定义的 preset 是错误（列出已定义的 preset），绝不静默
   回退到父会话模型。报错会指明 model 的真实来源，不把责任误归于 preset
-- preset 刻意高于 agentOverrides：profile 通过 agentOverrides 钉死角色模型（`loadCatalog`
+- preset 刻意高于 agentOverrides：通过 `agentOverrides` 钉死的角色模型（`loadCatalog`
   会先把它们折进 `agent.model`），若 preset 放在 frontmatter 同级则对它不可达。
   未引用 preset 的 agent 行为不变
 - 解析逻辑抽到 `src/agents/step-model.ts`（纯函数，便于单测）
@@ -636,41 +636,37 @@ Team selection is resolved as `PI_SUBAGENTS_TEAM` > `subagents.team` >
 string/object members, with `*` expanding all roles once and later object
 members applying the normal agent-override fields. Project team entries replace
 same-named user entries. Non-default team names are passed to child pane/tab
-processes as `PI_SUBAGENTS_TEAM`; `/subagents-team` manages project or user
+processes as `PI_SUBAGENTS_TEAM`; `/legion team` manages project or user
 settings.
 
 ### 6.4 总开关 `subagents.enabled`
 
-解析顺序：会话内覆盖（`/subagents-toggle`，仅内存，`/reload` 后回落） >
+解析顺序：会话内覆盖（`/legion on|off`，仅内存，`/reload` 后回落） >
 项目 `.pi/settings.json` > 用户 `~/.pi/agent/settings.json` > 默认 `true`。
+旧 toggle 的 `flip` 与无参数 `show` 用法已由显式 `/legion on` 或
+`/legion off` 取代；每次执行后都会显示最终状态。
 
-关闭后：launch 拒绝（`DISABLED` 错误码，指向 `/subagents-toggle on`）；
+关闭后：launch 拒绝（`DISABLED` 错误码，指向 `/legion on`）；
 system prompt 不再注入 playbook/roster；bash 派发 guard 放行手动 herdr
 命令。已有 children 不受影响——正常完成并通知，`status`/`collect`/
 `wait`/`resume`/`steer` 继续可用。
 
-### 6.4 模型档位 profile（对齐 pi-subagents）
+### 6.4.1 Scout guard `subagents.scoutGuard`
 
-角色不写死供应商模型。按 **cheap / medium / strong** 三档绑定：
+只在主会话生效（子进程带 `PI_SUBAGENT_ROLE`，不计数、不注入）。连续 N 次
+读类工具调用（`read`，以及可判定为只读的 bash：`cat`/`head`/`tail`/`less`/
+`rg`/`grep`/`find`/`ls`/`stat`/`wc`/`file`/`jq`、`git show|log|diff|status|blame`、
+不带 `-i` 的 `sed`）且中间没有成功的 `subagent` / `vexillatio` 派发时，异步
+注入一条 follow-up 提醒，不挡住当前 `tool_call`。
 
-| 档 | 角色 |
-| --- | --- |
-| cheap | scout, prototype |
-| medium | planner |
-| strong | worker, reviewer, designer |
-
-（advisor 为 cursor kind 自带模型，不参与 pi 档位。）
-
-流程：`/subagents-refresh-provider-models` 拉供应商目录 →
-`/subagents-generate-profiles` 写出 `<provider>.quota`（偏省）和
-`<provider>.quality`（偏强）→ `/subagents-load-profile` 写入
-`~/.pi/agent/settings.json` 的 `agentOverrides`。
-
-Profile 文件在 `~/.pi/agent/profiles/pi-legion/`。加载只替换
-`agentOverrides`（以及 profile 里显式带的 `subagents` 键），`modelScope` /
-`herdr` 等其它设置保留。项目 `.pi/settings.json` 覆盖用户设置。
+```json
+{ "subagents": { "scoutGuard": { "enabled": true, "threshold": 8, "cooldownMs": 120000 } } }
+```
 
----
+默认开启，`threshold` 8，`cooldownMs` 120000。提醒发出后计数清零并进入冷却；
+冷却期内不计数、不重复提醒。成功派发立即清零并退出冷却。`edit`/`write` 和
+写类 bash（含 `sed -i`、写重定向）清零但不进入冷却。无法判定的 bash 不计数
+也不清零。`/scout-guard` 开启、`/no-scout-guard` 关闭，只覆盖本会话。
 
 ## 7. 借鉴 pi-subagents：三类处理
 
@@ -893,13 +889,16 @@ function countToolErrors(turn: Turn): number {
 ```ts
 subagent({
   action?: "launch" | "continue" | "steer" | "resume" | "retire"
-         | "status" | "collect" | "list",     // 默认 launch
+         | "status" | "collect" | "wait" | "list" | "stop", // 默认 launch
 
   // launch
   agent?: string, task?: string,
   tasks?: Array<{ agent: string; task: string }>,   // 并行
   async?: boolean,          // 默认 true
   model?: string, cwd?: string, placement?: string,
+  worktree?: boolean,       // 隔离 git worktree（默认随角色）
+  verify?: string[],        // 收集时由扩展在子 worktree 里机械执行的验证命令；
+                            // 首个非零退出即 reject。子 agent 无需粘贴测试输出。
 
   // 续跑 / 控制
   name?: string,            // handle 名，如 "reviewer-1"
@@ -907,6 +906,18 @@ subagent({
 })
 ```
 
+#### `verify` 的信任链
+
+- launch 时 `verify` 合成一条带 `command` 的 acceptance criterion（`task-verify`），快照进子记录的 `pendingCriteria`；
+- collect 时 `applyVerification` 在子 worktree cwd 亲自执行（bash -lc，超时 SIGKILL）；
+- 全零退出 → `accepted (verified)`；首个非零 → `rejected`，reason 指名失败的命令；
+- 未提供 `verify` 时扩展**绝不猜命令**，保持 attested 语义不变（F44 边界）。
+
+配套设置（`~/.pi/agent/settings.json` → `subagents.legion`）：
+
+- `worktreeBootstrap`: 新建子 worktree 后自动准备依赖环境。`"npm-install"`（按 lockfile 选 pnpm/bun/yarn/npm）或任意 shell 命令（如 `"ln -sfn /path/to/node_modules ./node_modules"`）。幂等：`.pi-provisioned` 标记文件记录已应用的 mode，同 mode 重入直接跳过（resume 不重装）；mode 变更视为声明变更，重新执行。
+- `worktreeBootstrapTimeoutMs`: bootstrap 命令预算，默认 600s。失败即失败整个 launch，worktree 走既有回滚被整体移除。
+
 ### 动作语义
 
 | action | 用途 | 底层 |
@@ -916,7 +927,15 @@ subagent({
 | `steer` | **运行中插话改方向**（F10） | `agent prompt`（不等） |
 | `resume` | **已退出后恢复**（F12） | 新 pane + `--session <file>` |
 | `retire` | 回收 | ctrl+d / pane close / tab close |
-| `status` / `collect` / `list` | 查询 | `agent get` / jsonl / `agent list` |
+| `status` / `collect` / `list` | 查询 | child record / session JSONL |
+| `wait` | 等待指定或全部活动 child 完成；由 RPC settle 事件唤醒；ESC 中断时级联优雅关闭 children 后返回 | session runtime + RPC supervisor |
+| `stop` | 优雅停止指定或全部 tracked、非 retired children | `retire` 全链 + runtime release |
+
+### ESC abort 语义 + stop
+
+父 turn 的 ESC / RPC abort signal 会立即打断当前工具等待，并静默级联优雅关闭该 session 所拥有的 tracked children（包括 vexillatio utility children）。`wait` 返回 `interrupted (parent turn aborted)` 前先完成级联 retire；`collect` / inline collect 被中断时也会级联关闭 children，不生成显式 stop 的工具结果文案。级联先取消 completion watch，再并行 retire 并释放 runtime tracking；并发 abort 复用同一级联 promise。新的 turn 会建立新的级联周期。正常完成的 `wait` 仍由 RPC settle 事件立即解除，不需要等满 timeout。
+
+`stop` 是显式停止操作：`subagent({ action: "stop", name: "worker-0" })` 停一个 child，`subagent({ action: "stop", all: true })` 逐个停止当前跟踪的全部非 retired children。它复用 `retire` 生命周期（优雅关闭、超时后升级信号、后代清理）并释放 runtime 跟踪；`stop` 本身不接父 turn abort signal。`name` 与 `all` 互斥且必须指定其一。
 
 ### `continue` vs `steer` vs `resume`