pi-legion 0.16.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/CHANGELOG.md +117 -0
  2. package/CONTRIBUTING.md +109 -18
  3. package/README.md +389 -630
  4. package/agents/advisor.md +7 -5
  5. package/agents/centurion.md +53 -0
  6. package/agents/designer.md +33 -33
  7. package/agents/planner.md +1 -2
  8. package/agents/prototype.md +2 -2
  9. package/agents/reviewer.md +66 -31
  10. package/agents/scout.md +6 -2
  11. package/agents/worker.md +11 -3
  12. package/docs/contracts/esc-abort-v1.md +131 -0
  13. package/docs/contracts/esc-cascade-v2.md +101 -0
  14. package/docs/design.md +73 -37
  15. package/docs/legion-v2-contract.md +461 -0
  16. package/docs/legion-v2-delivery.md +62 -0
  17. package/docs/retire-hardening-contract.md +125 -0
  18. package/docs/subagents-teams.md +76 -0
  19. package/docs/tui-viewer-contract.md +276 -0
  20. package/docs/vexillatio-contract.md +162 -0
  21. package/index.ts +1568 -288
  22. package/package.json +19 -12
  23. package/skills/pi-legion/SKILL.md +86 -94
  24. package/src/agents/agents.ts +66 -16
  25. package/src/agents/overrides.ts +2 -1
  26. package/src/agents/paths.ts +1 -1
  27. package/src/agents/settings.ts +268 -20
  28. package/src/api.ts +49 -48
  29. package/src/{herdr → backends/legacy}/client.ts +14 -69
  30. package/src/{shared → backends/legacy}/cursor-chat.ts +2 -2
  31. package/src/{herdr → backends/legacy}/runner.ts +22 -9
  32. package/src/backends/legacy/types.ts +138 -0
  33. package/src/extension/auto-doctor.ts +144 -0
  34. package/src/extension/budget.ts +2 -2
  35. package/src/extension/child-guard.ts +214 -201
  36. package/src/extension/event-bus.ts +263 -0
  37. package/src/extension/legion-commands.ts +773 -0
  38. package/src/extension/legion-doctor.ts +975 -0
  39. package/src/extension/legion-status.ts +172 -0
  40. package/src/extension/legion-stop.ts +150 -0
  41. package/src/extension/legion-tools.ts +816 -0
  42. package/src/extension/notify.ts +24 -19
  43. package/src/extension/playbook.ts +20 -89
  44. package/src/extension/recycle.ts +2 -7
  45. package/src/extension/runtime.ts +736 -107
  46. package/src/extension/scout-guard.ts +492 -0
  47. package/src/extension/slash.ts +89 -438
  48. package/src/extension/spawn-hints.ts +79 -0
  49. package/src/extension/summary.ts +17 -58
  50. package/src/legion/budget.ts +165 -0
  51. package/src/legion/db.ts +242 -0
  52. package/src/legion/events.ts +150 -0
  53. package/src/legion/mail.ts +412 -0
  54. package/src/legion/nodes.ts +461 -0
  55. package/src/legion/rebuild.ts +533 -0
  56. package/src/legion/state-machine.ts +313 -0
  57. package/src/legion/usage.ts +101 -0
  58. package/src/runs/acceptance.ts +82 -25
  59. package/src/runs/args.ts +117 -15
  60. package/src/runs/hygiene.ts +335 -0
  61. package/src/runs/orchestrator.ts +808 -1681
  62. package/src/runs/owner.ts +61 -0
  63. package/src/runs/provider-pin.ts +59 -0
  64. package/src/runs/provision.ts +135 -0
  65. package/src/runs/role-tool-gates.ts +103 -0
  66. package/src/runs/store.ts +44 -17
  67. package/src/runs/verify-queue.ts +195 -0
  68. package/src/shared/name.ts +29 -0
  69. package/src/shared/output-cap.ts +57 -0
  70. package/src/shared/progress.ts +57 -135
  71. package/src/shared/session.ts +280 -173
  72. package/src/shared/types.ts +115 -208
  73. package/src/supervisor/child-memory.ts +140 -0
  74. package/src/supervisor/proc-tree.ts +103 -0
  75. package/src/supervisor/rpc-supervisor.ts +1033 -0
  76. package/src/supervisor/types.ts +153 -0
  77. package/src/supervisor/ui-proxy.ts +226 -0
  78. package/src/tui/chat-items.ts +330 -0
  79. package/src/tui/live-overlay.ts +874 -0
  80. package/src/tui/status.ts +553 -27
  81. package/src/tui/tree-view.ts +808 -0
  82. package/src/tui/viz/canvas.ts +119 -0
  83. package/src/tui/viz/layout.ts +111 -0
  84. package/src/tui/viz/model.ts +123 -0
  85. package/src/tui/viz/palette.ts +188 -0
  86. package/src/tui/viz/panels.ts +532 -0
  87. package/src/tui/viz/railway.ts +313 -0
  88. package/src/tui/viz/rate.ts +211 -0
  89. package/src/tui/viz/view.ts +228 -0
  90. package/src/extension/parent-label.ts +0 -115
  91. package/src/profiles/classify.ts +0 -375
  92. package/src/profiles/profiles.ts +0 -730
  93. package/src/runs/layout.ts +0 -258
@@ -0,0 +1,101 @@
1
+ # ESC 级联关闭契约(v2,2026-10-13 冻结)
2
+
3
+ ## 背景
4
+
5
+ v1(esc-abort-v1.md,已随 e66c85f 合入)冻结了「ESC ≠ 杀 children」语义。用户裁决推翻:turn 是 children 的 owner,turn 被 abort 时 children 应级联关闭,否则是资源泄漏。
6
+
7
+ ## 冻结决定
8
+
9
+ ### A. ESC 打断 turn → 级联优雅关闭 children
10
+
11
+ 改动点 `index.ts` 工具 execute(约 :687-691 的 `signal?.aborted` 快速返回处):
12
+
13
+ ```ts
14
+ if (signal?.aborted && action !== "stop") {
15
+ // NEW: cascade-close children owned by this turn before returning.
16
+ await cascadeRetireAll(); // fire-and-forget 也可以,但要保证 promise 存活到 retire 完成
17
+ return ok("interrupted (parent turn aborted)");
18
+ }
19
+ ```
20
+
21
+ **注意**:进入 execute 时 signal 已 aborted 的情况(ESC 发生在此工具调用排队后、执行前)——此时本 turn 尚未 launch 过任何 child,cascade 是 no-op,安全。
22
+
23
+ 但真正的触发点是**执行中途 abort**:wait/collect 正在 await 时 signal 才 abort。这些路径已有 interrupted 返回分支(waitAction / collectChild / collectInline / waitOne),在这些分支统一调 `cascadeRetireAll()`。
24
+
25
+ ### B. cascadeRetireAll 实现(index.ts)
26
+
27
+ ```ts
28
+ const cascadeRetireAll = async (): Promise<void> => {
29
+ // 1. runtime 跟踪的所有 jobs(与 stopAction all:true 相同的目标集)
30
+ for (const name of targets) runtime.cancelWatch(name); // 先停 watch,防 retire 期间通知噪音
31
+ await Promise.all([...jobs.map((job) => job.retire?.()), ...pendingUtilityRetires]); // 全部 best-effort catch
32
+ // 2. release 全部
33
+ };
34
+ ```
35
+
36
+ 复用 stopAction 的骨架但**不生成工具结果文案**(不是用户显式 stop,静默级联)。vexillatio 的 pendingUtilityRetires 一并级联。
37
+
38
+ ### C. wait/collect 中断路径统一接线
39
+
40
+ 所有「signal aborted → return interrupted」的分支(index.ts waitAction 间接层 + runtime.waitOne + collectChild + collectInline + launchFamily abandoned 路径)在返回前触发 cascade(一次性,防重入——用 module-level `cascading` promise 去重即可,同一 signal 只触发一次)。
41
+
42
+ **防重入**:同一 abort 事件可能同时命中多个 in-flight 工具调用(parallel tool calls),cascade 必须幂等:用 `let cascadePromise: Promise<void> | undefined` 缓存,已存在则复用。turn_start 时重置(新 turn 新级联)。
43
+
44
+ ### D. vexillatio collect 接 signal
45
+
46
+ `index.ts` launchUtilityFamily(约 :1895):
47
+ ```ts
48
+ const result = await handle.orchestrator.collect(handle.name, { timeoutMs, ...(signal ? { signal } : {}) });
49
+ ```
50
+ vexillatio 工具 execute 也要把 signal 传进来(找到它的 registerTool 调用,第 3 参数接上)。ESC 后 utility children 也应被 retire(它们进了 pendingUtilityRetires,cascade 覆盖)。
51
+
52
+ ### E. 契约/文档更新
53
+
54
+ - docs/contracts/esc-abort-v1.md:顶部加「v2 修订:ESC 语义改为级联关闭,推翻 v1 的『ESC ≠ 杀 children』」——保留原文供考古,加修订记录。
55
+ - docs/design.md、README.md、playbook(TOOL_DESCRIPTION / PARENT_PLAYBOOK)相应语句更新:ESC abort 会级联 retire children;wait 被打断时 children 一并关闭。
56
+
57
+ ## 语义边界(不变)
58
+
59
+ - **stop action 不变**:显式停止仍走全链。
60
+ - **主 pi 正常退出(quit)不变**:交互 TUI 的 session_shutdown 仍立即级联 retire。
61
+ - **非交互 print/JSON(#72)**:`ctx.mode` 为 `print` 或 `json` 时,session_shutdown 先等仍活着的 async 子 agent 结算(上限为各子的 turn timeout),再 retire 尚未结束的。避免 `--print` 在首包前把刚 spawn 的子进程记成 `no assistant message for the last prompt`。父会话关机导致的无 assistant abort 原因改为 parent session shutdown,与模型自己没写出 assistant 区分。
62
+ - **SIGKILL/崩溃不覆盖**:孤儿扫描 + resume 语义不变(这是既定接受的风险)。
63
+ - **children 的 children**:retire 链本身递归(孙进程 sweep 在 rpc-supervisor 的 retireChild 里),无需额外处理。
64
+ - **blocked children**:一并 retire(stop 语义一致)。
65
+
66
+ ## 文件归属
67
+
68
+ | 文件 | 改动 |
69
+ |---|---|
70
+ | index.ts | cascadeRetireAll + 各中断分支接线 + vexillatio signal |
71
+ | src/extension/playbook.ts | TOOL_DESCRIPTION / PARENT_PLAYBOOK 更新 |
72
+ | docs/contracts/esc-abort-v1.md | v2 修订记录 |
73
+ | docs/design.md, README.md | 语义说明 |
74
+ | test/unit/* | 新测试 |
75
+
76
+ ## v2.1 修订(2026-10-13,会话 01a13345 实测后补)
77
+
78
+ v2 的触发点只覆盖了「abort 落在 in-flight subagent 工具调用上」(wait/collect/launch 中途)。**async launch(默认形态)在 ESC 前就早已返回**:ESC 落在模型生成、空档或别的工具上时,没有任何 subagent 工具在执行,signal 无处投递,级联不触发——子 agent 继续跑,直到 session_shutdown 或显式 stop。
79
+
80
+ 实测:2026-10-13 03:20Z 会话 01a13345 async 启动 centurion(worktree),03:20:10 ESC abort 父 turn,子 agent 存活至用户退出父会话(03:20:24,走的是 session_shutdown 级联)。
81
+
82
+ **修复**:`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。
83
+
84
+ ## 验收
85
+
86
+ 1. typecheck + unit + integration 全绿。
87
+ 2. 新测试:wait 中途 abort → children 被 retire(mock 验证 retire 调用 + cancelWatch + release)。
88
+ 3. 新测试:cascade 幂等(同 signal 两次触发只 retire 一次)。
89
+ 4. 新测试:parallel 工具调用同时 abort,cascade 只跑一次。
90
+ 5. 新测试:vexillatio collect 在 abort 时提前返回(不长等 600s)。
91
+ 6. 新测试(v2.1):async launch 已返回后 emitSettled(true) → 子 agent 被 retire、无完成通知。
92
+ 7. 新测试(v2.1):emitSettled(false)(正常结算)→ 不 retire,async 子继续运行。
93
+
94
+ ## 锚点(以 master bc9c205 为准)
95
+
96
+ - index.ts:687-691(execute 入口 aborted 快速返回)
97
+ - index.ts:832-840(session_shutdown 参考——cascade 参考其形状)
98
+ - index.ts:2243-2280(stopAction 骨架——cascade 复用)
99
+ - index.ts:1890-1900(vexillatio collect)
100
+ - runtime.ts:481-590(waitOne interrupted 分支)
101
+ - master 上无 worktree 依赖,直接在主 repo 改。
package/docs/design.md CHANGED
@@ -1,5 +1,9 @@
1
1
  # pi-legion 设计文档
2
2
 
3
+ > **⚠️ 历史实验笔记(非现行契约)**
4
+ > 本文记录 herdr / pane 时代的实测与设计推演。**运行时契约以 [README](../README.md) 与 [CONTRIBUTING](../CONTRIBUTING.md) 为准**(Pi Legion 2.x = headless Pi RPC + `legion.db`;herdr pane 执行已归档到 `src/backends/legacy/`)。
5
+ > 下文 F 条中标 **✅ landed** 的是已在当前 master 落地的修复;未标注的早期结论仍有参考价值,但不要当作「今日仍坏」的缺口清单。
6
+
3
7
  > 基于 10 组实测实验(exp1–exp10)得出的设计。所有结论都标注了实验依据,
4
8
  > 未经验证的假设明确标记为「待验证」。
5
9
 
@@ -20,7 +24,7 @@
20
24
 
21
25
  ### 实现状态(相对本文档)
22
26
 
23
- 下面 F 条目里不少写的是「当时的缺口」。当前运行时已经钉死、以 [README](../README.md) 为准:
27
+ 下面 F 条目里不少写的是「当时的缺口」(文首 banner 已说明:契约以 README + CONTRIBUTING 为准)。当前运行时已经钉死:
24
28
 
25
29
  - 子进程强制加载 child-guard:拦 `herdr agent prompt|wait|send-keys|start`、外 pane read、只读角色写操作
26
30
  - 任务卡自动附录(禁止 wakeup、必须 `{"ok":…}`)
@@ -584,7 +588,7 @@ preset 规则:
584
588
  (`src/agents/step-model.ts`),只在该步骤确实引用了 preset 时生效
585
589
  - **响亮失败**:引用了未定义的 preset 是错误(列出已定义的 preset),绝不静默
586
590
  回退到父会话模型。报错会指明 model 的真实来源,不把责任误归于 preset
587
- - preset 刻意高于 agentOverrides:profile 通过 agentOverrides 钉死角色模型(`loadCatalog`
591
+ - preset 刻意高于 agentOverrides:通过 `agentOverrides` 钉死的角色模型(`loadCatalog`
588
592
  会先把它们折进 `agent.model`),若 preset 放在 frontmatter 同级则对它不可达。
589
593
  未引用 preset 的 agent 行为不变
590
594
  - 解析逻辑抽到 `src/agents/step-model.ts`(纯函数,便于单测)
@@ -636,41 +640,38 @@ Team selection is resolved as `PI_SUBAGENTS_TEAM` > `subagents.team` >
636
640
  string/object members, with `*` expanding all roles once and later object
637
641
  members applying the normal agent-override fields. Project team entries replace
638
642
  same-named user entries. Non-default team names are passed to child pane/tab
639
- processes as `PI_SUBAGENTS_TEAM`; `/subagents-team` manages project or user
643
+ processes as `PI_SUBAGENTS_TEAM`; `/legion team` manages project or user
640
644
  settings.
641
645
 
642
646
  ### 6.4 总开关 `subagents.enabled`
643
647
 
644
- 解析顺序:会话内覆盖(`/subagents-toggle`,仅内存,`/reload` 后回落) >
648
+ 解析顺序:会话内覆盖(`/legion on|off`,仅内存,`/reload` 后回落) >
645
649
  项目 `.pi/settings.json` > 用户 `~/.pi/agent/settings.json` > 默认 `true`。
650
+ 旧 toggle 的 `flip` 与无参数 `show` 用法已由显式 `/legion on` 或
651
+ `/legion off` 取代;每次执行后都会显示最终状态。
646
652
 
647
- 关闭后:launch 拒绝(`DISABLED` 错误码,指向 `/subagents-toggle on`);
653
+ 关闭后:launch 拒绝(`DISABLED` 错误码,指向 `/legion on`);
648
654
  system prompt 不再注入 playbook/roster;bash 派发 guard 放行手动 herdr
649
655
  命令。已有 children 不受影响——正常完成并通知,`status`/`collect`/
650
656
  `wait`/`resume`/`steer` 继续可用。
651
657
 
652
- ### 6.4 模型档位 profile(对齐 pi-subagents)
653
-
654
- 角色不写死供应商模型。按 **cheap / medium / strong** 三档绑定:
655
-
656
- | 档 | 角色 |
657
- | --- | --- |
658
- | cheap | scout, prototype |
659
- | medium | planner |
660
- | strong | worker, reviewer, designer |
661
-
662
- (advisor 为 cursor kind 自带模型,不参与 pi 档位。)
658
+ ### 6.4.1 Scout guard `subagents.scoutGuard`
663
659
 
664
- 流程:`/subagents-refresh-provider-models` 拉供应商目录 →
665
- `/subagents-generate-profiles` 写出 `<provider>.quota`(偏省)和
666
- `<provider>.quality`(偏强)→ `/subagents-load-profile` 写入
667
- `~/.pi/agent/settings.json` 的 `agentOverrides`。
660
+ 只在主会话生效(子进程带 `PI_SUBAGENT_ROLE`,不计数、不注入)。连续 N 次
661
+ 读类工具调用(first-class `read`/`grep`/`find`/`ls`,以及可判定为只读的 bash:
662
+ `cat`/`head`/`tail`/`less`/`rg`/`grep`/`find`/`ls`/`stat`/`wc`/`file`/`jq`、
663
+ `git show|log|diff|status|blame`、不带 `-i` 的 `sed`)且中间没有成功的
664
+ `subagent` / `vexillatio` 派发时,异步注入一条 follow-up 提醒,不挡住当前
665
+ `tool_call`。
668
666
 
669
- Profile 文件在 `~/.pi/agent/profiles/pi-legion/`。加载只替换
670
- `agentOverrides`(以及 profile 里显式带的 `subagents` 键),`modelScope` /
671
- `herdr` 等其它设置保留。项目 `.pi/settings.json` 覆盖用户设置。
667
+ ```json
668
+ { "subagents": { "scoutGuard": { "enabled": true, "threshold": 8, "cooldownMs": 120000 } } }
669
+ ```
672
670
 
673
- ---
671
+ 默认开启,`threshold` 8,`cooldownMs` 120000。提醒发出后计数清零并进入冷却;
672
+ 冷却期内不计数、不重复提醒。成功派发立即清零并退出冷却。`edit`/`write` 和
673
+ 写类 bash(含 `sed -i`、写重定向)清零但不进入冷却。无法判定的 bash 不计数
674
+ 也不清零。`/scout-guard` 开启、`/no-scout-guard` 关闭,只覆盖本会话。
674
675
 
675
676
  ## 7. 借鉴 pi-subagents:三类处理
676
677
 
@@ -893,13 +894,16 @@ function countToolErrors(turn: Turn): number {
893
894
  ```ts
894
895
  subagent({
895
896
  action?: "launch" | "continue" | "steer" | "resume" | "retire"
896
- | "status" | "collect" | "list", // 默认 launch
897
+ | "status" | "collect" | "wait" | "list" | "stop", // 默认 launch
897
898
 
898
899
  // launch
899
900
  agent?: string, task?: string,
900
901
  tasks?: Array<{ agent: string; task: string }>, // 并行
901
902
  async?: boolean, // 默认 true
902
903
  model?: string, cwd?: string, placement?: string,
904
+ worktree?: boolean, // 隔离 git worktree(默认随角色)
905
+ verify?: string[], // 收集时由扩展在子 worktree 里机械执行的验证命令;
906
+ // 首个非零退出即 reject。子 agent 无需粘贴测试输出。
903
907
 
904
908
  // 续跑 / 控制
905
909
  name?: string, // handle 名,如 "reviewer-1"
@@ -907,6 +911,18 @@ subagent({
907
911
  })
908
912
  ```
909
913
 
914
+ #### `verify` 的信任链
915
+
916
+ - launch 时 `verify` 合成一条带 `command` 的 acceptance criterion(`task-verify`),快照进子记录的 `pendingCriteria`;
917
+ - collect 时 `applyVerification` 在子 worktree cwd 亲自执行(bash -lc,超时 SIGKILL);
918
+ - 全零退出 → `accepted (verified)`;首个非零 → `rejected`,reason 指名失败的命令;
919
+ - 未提供 `verify` 时扩展**绝不猜命令**,保持 attested 语义不变(F44 边界)。
920
+
921
+ 配套设置(`~/.pi/agent/settings.json` → `subagents.legion`):
922
+
923
+ - `worktreeBootstrap`: 新建子 worktree 后自动准备依赖环境。`"npm-install"`(按 lockfile 选 pnpm/bun/yarn/npm)或任意 shell 命令(如 `"ln -sfn /path/to/node_modules ./node_modules"`)。幂等:`.pi-provisioned` 标记文件记录已应用的 mode,同 mode 重入直接跳过(resume 不重装);mode 变更视为声明变更,重新执行。
924
+ - `worktreeBootstrapTimeoutMs`: bootstrap 命令预算,默认 600s。失败即失败整个 launch,worktree 走既有回滚被整体移除。
925
+
910
926
  ### 动作语义
911
927
 
912
928
  | action | 用途 | 底层 |
@@ -916,7 +932,15 @@ subagent({
916
932
  | `steer` | **运行中插话改方向**(F10) | `agent prompt`(不等) |
917
933
  | `resume` | **已退出后恢复**(F12) | 新 pane + `--session <file>` |
918
934
  | `retire` | 回收 | ctrl+d / pane close / tab close |
919
- | `status` / `collect` / `list` | 查询 | `agent get` / jsonl / `agent list` |
935
+ | `status` / `collect` / `list` | 查询 | child record / session JSONL |
936
+ | `wait` | 等待指定或全部活动 child 完成;由 RPC settle 事件唤醒;ESC 中断时级联优雅关闭 children 后返回 | session runtime + RPC supervisor |
937
+ | `stop` | 优雅停止指定或全部 tracked、非 retired children | `retire` 全链 + runtime release |
938
+
939
+ ### ESC abort 语义 + stop
940
+
941
+ 父 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。
942
+
943
+ `stop` 是显式停止操作:`subagent({ action: "stop", name: "worker-0" })` 停一个 child,`subagent({ action: "stop", all: true })` 逐个停止当前跟踪的全部非 retired children。它复用 `retire` 生命周期(优雅关闭、超时后升级信号、后代清理)并释放 runtime 跟踪;`stop` 本身不接父 turn abort signal。`name` 与 `all` 互斥且必须指定其一。
920
944
 
921
945
  ### `continue` vs `steer` vs `resume`
922
946
 
@@ -1113,12 +1137,24 @@ index.ts(132,4): error TS7006: Parameter 'signal' implicitly has an 'any' type.
1113
1137
 
1114
1138
  ---
1115
1139
 
1116
- ## 16. 交付前安全/健壮性审计(F38–F45)
1140
+ ## 16. 交付前安全/健壮性审计(F38–F46)— Historical findings(✅ landed)
1117
1141
 
1118
1142
  对全部模块做了对抗式输入扫描(畸形会话文件、路径穿越、恶意配置、并发写)。
1119
- 以下 8 条是真缺陷,其余区域已验证健壮。
1143
+ 以下条目**当时**是真缺陷;对照当前 master 均已落地(见各条 ✅),勿再当 open gap。
1120
1144
 
1121
- ### F38 — ReDoS:glob → RegExp 的嵌套量词(安全)
1145
+ | # | 当时缺口 | master 落点(摘要) |
1146
+ | --- | --- | --- |
1147
+ | F38 | glob→RegExp ReDoS | `matchesScopePattern` 双指针 glob,**不用 RegExp** |
1148
+ | F39 | `openSync`/`closeSync` fd 泄漏 | session 预创建改 `writeFileSync(..., { flag: "wx" })` |
1149
+ | F40 | `JSON.parse` 标量拖垮会话解析 | `decodeEvent` 非对象计入 `tornLines` |
1150
+ | F41 | `tasks[]` 条目未校验 | `firstInvalidStep` / 启动前校验 agent+task |
1151
+ | F42 | 空白 `task` 被 `Boolean` 放行 | 存在性按 `trim()` |
1152
+ | F43 | 角色 `timeoutMs` 被忽略 | launch 记入 `timeoutByName`,follow/wait 使用 |
1153
+ | F44 | `acceptance.criteria` 静默丢弃 | `pendingCriteria` + command 才升 `verified` |
1154
+ | F45 | 未生效配置看起来生效 | `UNENFORCED_FIELDS` 现为空;list 不再假警告 |
1155
+ | F46 | 嵌套 YAML acceptance 未解析 | `parseAcceptance` + `parseIndentedBlock` |
1156
+
1157
+ ### F38 — ✅ landed — ReDoS:glob → RegExp 的嵌套量词(安全)
1122
1158
 
1123
1159
  `modelScope.allow` 的 glob 被翻译成 `.*`,于是 `*a*a*a…b` 变成 `.*a.*a.*a…b`——
1124
1160
  嵌套量词在**不匹配**的输入上指数回溯。
@@ -1133,7 +1169,7 @@ index.ts(132,4): error TS7006: Parameter 'signal' implicitly has an 'any' type.
1133
1169
  **修法**:不用正则,改用双指针贪心 glob 匹配(只回溯最近一个 `*`)。
1134
1170
  修复后 n=6400 仅 2ms。
1135
1171
 
1136
- ### F39 — fd 泄漏:`openSync`/`closeSync` 无保护
1172
+ ### F39 — ✅ landed — fd 泄漏:`openSync`/`closeSync` 无保护
1137
1173
 
1138
1174
  ```ts
1139
1175
  const fd = fs.openSync(file, "w", 0o600);
@@ -1146,7 +1182,7 @@ launcher 为**每个 child** 创建一个 session 文件,所以泄漏会随 fa
1146
1182
  **修法**:`fs.writeFileSync(file, "", { flag: "wx", mode: 0o600 })`——
1147
1183
  由 Node 自己管理描述符,并且 `wx` 顺带消除了 `existsSync` 检查留下的 TOCTOU 窗口。
1148
1184
 
1149
- ### F40 — `JSON.parse("null")` 拖垮整个会话解析
1185
+ ### F40 — ✅ landed — `JSON.parse("null")` 拖垮整个会话解析
1150
1186
 
1151
1187
  `JSON.parse` 对标量是成功的:`null` / `42` / `true` / `"x"`。
1152
1188
  随后 `event.type` 在 `null` 上抛异常,**整个 `parseSessionText` 崩溃**,
@@ -1154,7 +1190,7 @@ launcher 为**每个 child** 创建一个 session 文件,所以泄漏会随 fa
1154
1190
 
1155
1191
  **修法**:非对象、非数组的标量按损坏行计入 `tornLines`,继续解析其余行。
1156
1192
 
1157
- ### F41 — `tasks[]` 的条目未校验
1193
+ ### F41 — ✅ landed — `tasks[]` 的条目未校验
1158
1194
 
1159
1195
  单任务路径用 `Boolean(params.agent && params.task)` 把关,但数组路径直接放行:
1160
1196
 
@@ -1165,12 +1201,12 @@ tasks:[{task:"do it"}] → 放行,agent 名为 undefined
1165
1201
 
1166
1202
  **修法**:每个 step 在分配任何资源之前校验 `agent` 与 `task`。
1167
1203
 
1168
- ### F42 — `Boolean(" ")` 为真:纯空白 task 被放行
1204
+ ### F42 — ✅ landed — `Boolean(" ")` 为真:纯空白 task 被放行
1169
1205
 
1170
1206
  即使单任务路径,`task: " "` 也会通过,生成一个毫无意义的 `Task:` prompt。
1171
1207
  **修法**:存在性按 `trim()` 后的内容判定,而非 `Boolean()`。
1172
1208
 
1173
- ### F43 — `timeoutMs` 被解析却从不生效
1209
+ ### F43 — ✅ landed — `timeoutMs` 被解析却从不生效
1174
1210
 
1175
1211
  5 个自带角色都声明了预算,运行时却全部忽略,永远用全局默认 15 分钟:
1176
1212
 
@@ -1182,7 +1218,7 @@ DEFAULTS.turnTimeoutMs: 900000 (15min) ← 实际生效
1182
1218
 
1183
1219
  **修法**:`collect` 采用 `agent.timeoutMs`(按 child 记录,逐个子 agent 生效)。
1184
1220
 
1185
- ### F44 — `acceptance.criteria` 被静默丢弃
1221
+ ### F44 — ✅ landed — `acceptance.criteria` 被静默丢弃
1186
1222
 
1187
1223
  角色可以声明 `must: "测试通过"` 这类**语义**验收条件,代码解析后就不管了。
1188
1224
  调用方无法知道「没有任何东西验证过它」。
@@ -1193,7 +1229,7 @@ DEFAULTS.turnTimeoutMs: 900000 (15min) ← 实际生效
1193
1229
  **修法**:criteria 作为**待验证清单**回传调用方(`pendingCriteria`),
1194
1230
  且 `level` 保持 `attested`——**`verified` 只留给真正被人核对过的证据**。
1195
1231
 
1196
- ### F45 — 配置字段「看起来生效、实际无效」
1232
+ ### F45 — ✅ landed — 配置字段「看起来生效、实际无效」
1197
1233
 
1198
1234
  自带角色携带 `onBlocked` / `allowNestedSubagents` / `fallbackModels` / `toolTimeoutMs`,
1199
1235
  全部被解析、全部不生效。其中 `allowNestedSubagents: false` 最危险——
@@ -1208,7 +1244,7 @@ DEFAULTS.turnTimeoutMs: 900000 (15min) ← 实际生效
1208
1244
  **原则**:**一个被接受却不做事的键,比一个未知的键更危险**——
1209
1245
  用户会相信它已经在保护自己。
1210
1246
 
1211
- ### F46 — 嵌套 YAML 块从未被解析:自带角色的 acceptance 全部丢失
1247
+ ### F46 — ✅ landed — 嵌套 YAML 块从未被解析:自带角色的 acceptance 全部丢失
1212
1248
 
1213
1249
  frontmatter 解析器是**扁平的**(只处理 `key: value`);一个嵌套块会以
1214
1250
  **剥掉公共缩进后的原始文本**返回: