pi-legion 3.1.0 → 5.0.0

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 (85) hide show
  1. package/CHANGELOG.md +382 -2
  2. package/CONTRIBUTING.md +4 -17
  3. package/README.md +127 -66
  4. package/agents/centurion.md +20 -16
  5. package/agents/scout.md +3 -1
  6. package/agents/worker.md +6 -8
  7. package/docs/contracts/declarative-phase-machine-v5.md +128 -0
  8. package/docs/contracts/display-liveness-v1.md +373 -0
  9. package/docs/contracts/drop-non-pi-kinds-v4.md +198 -0
  10. package/docs/contracts/esc-abort-v1.md +4 -4
  11. package/docs/contracts/esc-no-retire-v3.md +2 -2
  12. package/docs/contracts/launch-admission-queue-v1.md +839 -0
  13. package/docs/contracts/status-panel-v1.md +174 -0
  14. package/docs/contracts/subagent-renewal-v1.md +260 -0
  15. package/docs/headless-child-contract.md +6 -3
  16. package/docs/inprocess-supervisor.md +106 -27
  17. package/docs/legion-v2-contract.md +27 -2
  18. package/docs/performance-2026-10-19.md +199 -0
  19. package/docs/spawn-mode-visibility-v1.md +4 -1
  20. package/docs/vexillatio-contract.md +3 -1
  21. package/index.ts +1155 -120
  22. package/package.json +5 -3
  23. package/skills/pi-legion/SKILL.md +2 -3
  24. package/src/agents/agents.ts +310 -46
  25. package/src/agents/overrides.ts +3 -2
  26. package/src/agents/presets.ts +14 -40
  27. package/src/agents/settings.ts +32 -95
  28. package/src/agents/step-model.ts +7 -22
  29. package/src/api.ts +1 -35
  30. package/src/extension/child-guard.ts +25 -1
  31. package/src/extension/event-bus.ts +80 -8
  32. package/src/extension/legion-commands.ts +41 -17
  33. package/src/extension/legion-doctor.ts +1 -1
  34. package/src/extension/legion-stop.ts +39 -13
  35. package/src/extension/legion-tools.ts +87 -25
  36. package/src/extension/liveness.ts +200 -0
  37. package/src/extension/notify.ts +136 -4
  38. package/src/extension/playbook.ts +4 -4
  39. package/src/extension/recycle.ts +4 -0
  40. package/src/extension/runtime.ts +435 -16
  41. package/src/extension/slash.ts +0 -21
  42. package/src/extension/summary.ts +14 -5
  43. package/src/extension/timing.ts +8 -4
  44. package/src/legion/db.ts +165 -1
  45. package/src/legion/events.ts +81 -16
  46. package/src/legion/nodes.ts +13 -2
  47. package/src/legion/phase-conditions.ts +164 -0
  48. package/src/legion/phase-machine.ts +403 -0
  49. package/src/legion/rebuild.ts +7 -1
  50. package/src/legion/state-machine.ts +219 -115
  51. package/src/legion/usage.ts +58 -4
  52. package/src/runs/args.ts +32 -18
  53. package/src/runs/extension-inheritance.ts +220 -0
  54. package/src/runs/orchestrator.ts +1292 -96
  55. package/src/runs/progress-signal.ts +137 -0
  56. package/src/runs/store-lookup.ts +270 -0
  57. package/src/runs/worktree.ts +190 -21
  58. package/src/shared/ignored-kind.ts +57 -0
  59. package/src/shared/progress.ts +11 -0
  60. package/src/shared/session.ts +199 -19
  61. package/src/shared/types.ts +138 -69
  62. package/src/supervisor/admission-queue.ts +516 -0
  63. package/src/supervisor/child-context.ts +19 -0
  64. package/src/supervisor/inprocess-supervisor.ts +137 -38
  65. package/src/supervisor/proc-memory.ts +67 -0
  66. package/src/supervisor/routing-supervisor.ts +60 -2
  67. package/src/supervisor/rpc-supervisor.ts +2 -2
  68. package/src/tui/session-messages-file.ts +100 -0
  69. package/src/tui/status.ts +91 -18
  70. package/src/tui/tree-view.ts +84 -3
  71. package/src/tui/viz/layout.ts +54 -3
  72. package/src/tui/viz/model.ts +67 -14
  73. package/src/tui/viz/palette.ts +11 -3
  74. package/src/tui/viz/panels.ts +222 -8
  75. package/src/tui/viz/view.ts +110 -23
  76. package/agents/advisor.md +0 -110
  77. package/agents/designer.md +0 -87
  78. package/agents/planner.md +0 -53
  79. package/agents/prototype.md +0 -72
  80. package/agents/reviewer.md +0 -113
  81. package/src/backends/legacy/client.ts +0 -638
  82. package/src/backends/legacy/cursor-chat.ts +0 -348
  83. package/src/backends/legacy/runner.ts +0 -101
  84. package/src/backends/legacy/types.ts +0 -138
  85. package/src/runs/kind.ts +0 -260
@@ -0,0 +1,174 @@
1
+ # Status panel v1 — `/legion` 大盘的 status 面板 + status 字段缺口补齐
2
+
3
+ > 冻结契约。合并权人裁定,worker 不得自行解释矛盾,遇矛盾向父会话报告。
4
+ > 基线:`3071dee` (3.1.0),`npm run typecheck` = 0、`npm test` = 0。
5
+
6
+ ## 0. 目标
7
+
8
+ 1. 在 `/legion` 全屏大盘(`src/tui/viz/`)新增 `status` 面板,把目前只存在于聊天文本里的 `/legion status` 数据搬到大盘上。
9
+ 2. 补齐 `/legion status` 的已知缺口:`supervisor=unknown`、`owner` 缺失、无内存、无 context tokens、`usage` 未格式化。
10
+
11
+ ## 1. 不可违反的既有约束
12
+
13
+ | 约束 | 锚点 |
14
+ | --- | --- |
15
+ | **禁止给 `legion.db` 加列、禁止升 `LEGION_DB_USER_VERSION`** | `docs/spawn-mode-visibility-v1.md:143`、`test/unit/legion-schema-sentinel.test.ts` |
16
+ | 运行时零外部依赖(Node stdlib only) | `CONTRIBUTING.md:215` |
17
+ | 每行 `visibleWidth === w`(严格相等,非 ≤) | `test/unit/legion-viz.test.ts:417-434,628,911,1464,1630` |
18
+ | 平台降级不得抛错:非 Linux 返回空值 | 先例 `src/supervisor/proc-tree.ts:44` |
19
+ | `spawnMode` 缺失必须渲染 `unknown`,**绝不猜 `rpc`** | `src/extension/runtime.ts:84-89`、`test/unit/runtime.test.ts:1490-1501` |
20
+
21
+ ## 2. 设计决策
22
+
23
+ ### D1 — 新增第 5 个 pane,但 portrait 不渲染
24
+
25
+ - `wide` / `stacked` 新增 `status` rect;`portrait` 的 `layout.status` 返回**零面积 rect** `{x,y,w:0,h:0}`。
26
+ - 理由:portrait `46×24` 实测 `galaxy=5 chart=10 timing=3 log=3`,`bodyH=21`,4 个 pane 最小高之和 `3+10+3+3=19`,仅剩 2 行 —— 物理上装不下第 5 个 pane(最小 3 行)。`timing`/`log` 在 `h=3` 时内框 `h=1`,`drawTiming`/`drawLog` 本就提前 return,**portrait 极矮时这两个 pane 已是空壳**。
27
+ - `frame()` 在 `h<3` 已早退且不画任何东西,所以零面积 rect 天然安全,无需特判绘制。
28
+ - **Tab 必须跳过零面积 pane**:新增 `availablePanes(layout)`,返回 `h>0` 的 pane 列表;`handleViewKey` 增加可选第 4 参 `panes`,**缺省 = 全部 pane**(保证既有测试不变)。
29
+ - 被否决:(a) 全布局都加 → portrait 溢出 footer;(b) status 复用 timing 做可切换视图 → 隐藏态发现性差,且 `drawTiming` 宽度算术已很紧;(c) 把 status 塞进 log → 语义冲突。
30
+
31
+ ### D2 — inprocess 内存口径:只显示 host rss,禁止按子 agent 摊派
32
+
33
+ - `rpc` 子 agent:有独立 pid → 显示 per-child `rss`。
34
+ - `inprocess` 子 agent:**没有独立进程**(`inprocess-supervisor.ts:751-754` 只返回 name+sessionFile)。面板与 status 文本中 **inprocess 行的 rss 列留空/`—`**,另起一行显示 `host rss <N> MB · shared by N inprocess`。
35
+ - **严禁**按 token 比例把 host rss 摊到子 agent 头上 —— 那是编造数据,用户会拿它做决策。
36
+ - 理由:诚实性优先于信息密度。
37
+
38
+ ### D3 — pid 穿透(不加 DB 列)
39
+
40
+ 链路:`ChildHandle.pid` → `Handle.pid` → `TrackedJobInput.pid` → `StatusEntry.pid` → `VizNode.pid`。
41
+
42
+ - `src/shared/types.ts:482` `Handle` **当前无 pid**,必须加 `pid?: number`。
43
+ - `src/runs/orchestrator.ts:800` 附近(`spawnMode: mode` 同处)写入 `...(result.pid ? { pid: result.pid } : {})`。
44
+ - `TrackedJobInput`(`src/extension/runtime.ts:73-107`)加 `pid?: number`;`index.ts:2675` 的 `runtime.track({...})` 补传。
45
+ - pid 不落盘是既有事实,**不新增持久化**——viz 只在当前宿主进程可见,跨进程显示为未知。
46
+
47
+ ### D4 — context tokens:扩 `ParsedSession`,不做百分比
48
+
49
+ - `accumulateUsage`(`src/shared/session.ts:124-136`)在累加的同时,把**最后一条 assistant message** 的 `input + cacheRead + cacheWrite` 记到 `ParsedSession.lastContextTokens`。
50
+ - `LiveProgress`(`src/shared/progress.ts:9-28`)加 `contextTokens?: number`;`progressFromSession` 投影;`mergeProgress` 用「later wins」语义。
51
+ - **不显示百分比**:`contextWindow` 在 JSONL 中不存在,全仓零命中。要百分比就得引模型注册表,超出本契约范围。显示绝对值 `ctx 24.3K tok`。
52
+ - 被否决:直读 session JSONL 最后一条 assistant usage → 与既有 `parseSessionFile` 重复解析,且绕过 `accumulateUsage` 单一事实源。
53
+
54
+ ### D5 — 修 `childStatus` 漏传(现存 bug)
55
+
56
+ `index.ts:926-946` 的 `childStatus` 回调补 `spawnMode` 与 `owner`:
57
+
58
+ - `spawnMode: child.spawnMode`(run.json 已有值,`src/shared/types.ts:365-373`)
59
+ - `owner:` 用既有 `runOwnerStatus(runDir)`(`src/runs/owner.ts:60` 返回 `live|dead|unknown`)
60
+ - 正确范例:`index.ts:1417-1428`、`index.ts:2887-2899`(这两处**已传** spawnMode)。
61
+ - 这是纯 bug fix,与新增面板解耦,可独立验收。
62
+
63
+ ### D6 — 所有新字段一律 optional
64
+
65
+ `VizNode` 新增字段必须 optional,否则 3 处字面量构造编译失败:`test/unit/legion-viz.test.ts:18-20`、`test/unit/legion-stop.test.ts:92`、`src/tui/viz/panels.ts:103-105`。
66
+
67
+ 投影沿用仓库惯例 `...(cond ? {k:v} : {})`(`model.ts:72-79`),**不写 `undefined` 字面量**。
68
+
69
+ ### D7 — status 面板字段集与宽度降级档位
70
+
71
+ 表头 1 行 + 可选页脚 1 行;列按**绝对列数**分层(沿用 `drawTiming` 惯例):
72
+
73
+ | 内框宽 | 列 |
74
+ | --- | --- |
75
+ | `w >= 72` | `name · role · state · supervisor · ctx · rss · turns` |
76
+ | `w >= 52` | `name · state · supervisor · ctx` |
77
+ | `w >= 36` | `name · state · ctx` |
78
+ | `w >= 20` | `name · state` |
79
+ | `w < 20` | 不画(return) |
80
+
81
+ - 守卫:`if (r.w < 20 || r.h < 2) return;`(`drawTiming` 用 `w<8,h<2`;本面板列多,下限提到 20)
82
+ - `footerH = rows.length > 0 && r.h >= 4 ? 1 : 0`;`rowsAvail = max(0, r.h - 1 - footerH)`
83
+ - **所有 `cv.text` 必须带 `maxX` 或先 `ellipsize`** —— 禁止复制 `drawLog`(`panels.ts:530-532`)的越界 bug。
84
+ - `rss` 列:rpc → `152M`;inprocess → `—`;未知 → `—`。**不得写大写单位**(`legion-viz.test.ts:927` 的字符类只含小写 a-z),用 `M` 会红 → 改用 `m`;或把该断言一并更新(见 §5)。
85
+
86
+ ### D8 — Tab 顺序:status 追加到末尾
87
+
88
+ `PANES = ["galaxy","chart","timing","log","status"]`(`src/tui/viz/view.ts:36`)。
89
+
90
+ - 追加在末尾使 `legion-viz.test.ts:442`(chart)、`:444`(timing)、`:446`(log)**全部继续通过**,只需新增一条 status 断言。
91
+ - 被否决:插入 timing 与 log 之间 → 直接打红 3 条既有断言,且 `:1588-1593` 再红一条。
92
+
93
+ ## 3. 文件所有权(严格边界,禁止越界)
94
+
95
+ ### Worker A — 数据管道 + status 文本(先做)
96
+
97
+ | 文件 | 性质 |
98
+ | --- | --- |
99
+ | `src/supervisor/proc-memory.ts` | **新增**:`readProcRss(pid)`,读 `/proc/<pid>/status` 的 `VmRSS`/`VmHWM`,非 Linux / 读失败 / pid 已退 → `undefined`,绝不抛 |
100
+ | `src/shared/types.ts` | 改:`Handle.pid?`、`ParsedSession.lastContextTokens?` |
101
+ | `src/shared/session.ts` | 改:`accumulateUsage` 记录最后一条 assistant 的 context tokens |
102
+ | `src/shared/progress.ts` | 改:`LiveProgress.contextTokens?` + `progressFromSession` + `mergeProgress` |
103
+ | `src/runs/orchestrator.ts` | 改:`Handle` 写入 `pid` |
104
+ | `src/extension/runtime.ts` | 改:`TrackedJobInput.pid?`、`statusEntryFromJob`/`statusEntryFromNode` 写 `spawnMode/pid/contextTokens/rss`、`renderLiveChildStatus` 增 memory/ctx 行 |
105
+ | `src/tui/status.ts` | 改:`StatusEntry` 加 `spawnMode?/pid?/contextTokens?/rss?`(**不动 `formatWidgetLines`**) |
106
+ | `index.ts` | 改:`childStatus` 补 `spawnMode`/`owner`;`runtime.track` 补 `pid` |
107
+ | `test/unit/proc-memory.test.ts` | **新增** |
108
+ | `test/unit/legion-status.test.ts` | 改:新增字段断言(`:110-147`、`:192-254` 现有断言**不得放宽**,只追加) |
109
+ | `test/unit/runtime.test.ts` | 改:`renderLiveChildStatus` 新行断言 |
110
+
111
+ **Worker A 严禁触碰**:`src/tui/viz/**`、`src/tui/tree-view.ts`、`src/tui/live-overlay.ts`、`docs/**`。
112
+
113
+ ### Worker B — viz 面板(等 A 合入后)
114
+
115
+ | 文件 | 性质 |
116
+ | --- | --- |
117
+ | `src/tui/viz/layout.ts` | 改:`LegionLayout.status: Rect` + 三批分支 + `availablePanes` |
118
+ | `src/tui/viz/panels.ts` | 改:`Pane` 联合加 `"status"`;**新增 `drawStatus`**;**不修改** 既有 4 个 draw* |
119
+ | `src/tui/viz/view.ts` | 改:`PANES` 末尾追加;`frame`+`drawStatus` 调用;`clampList` 支持 `"status"`;`handleViewKey` 第 4 参 `panes` |
120
+ | `src/tui/viz/model.ts` | 改:`VizNode` 加 optional 字段 + `nodesFromEntries` 投影 |
121
+ | `test/unit/legion-viz.test.ts` | 改:新增 status 面板断言(§5 清单) |
122
+
123
+ **Worker B 严禁触碰**:`src/extension/**`、`src/shared/**`、`src/runs/**`、`src/tui/status.ts`、`index.ts`。
124
+
125
+ ## 4. 分阶段与验收
126
+
127
+ | 阶段 | 内容 | 验收 |
128
+ | --- | --- | --- |
129
+ | P1 | Worker A 全量 | `npm run typecheck` && `npm test` |
130
+ | P2 | Worker B 全量(依赖 P1 已合入) | `npm run typecheck` && `npm test` |
131
+
132
+ 每个阶段必须 **typecheck 0 / test 0**。首个非零退出即判 rejected。
133
+
134
+ ## 5. 必须同步更新的测试(逐条)
135
+
136
+ | 测试 | 原因 | 期望 |
137
+ | --- | --- | --- |
138
+ | `legion-viz.test.ts:417-434` | 新增 status 面板标题 | 追加 `plain.some(l => l.includes("status"))`;**不得放宽** `visibleWidth === w` |
139
+ | `legion-viz.test.ts:437-459` | Tab 顺序末尾新增 | 在 `:446` 后追加 `handleViewKey("\t")` → `assert.equal(state.focus, "status")`;既有 3 条保留 |
140
+ | `legion-viz.test.ts:160-183` | layout 新字段 | `for (const r of [galaxy,chart,timing,log,status])` 加入界内断言;**portrait 跳过 status**(零面积) |
141
+ | `legion-viz.test.ts:872-901` | 几何锁 | portrait 段保持四段相接断言不变;wide 段新增「右列三段相接」断言 |
142
+ | `legion-viz.test.ts:927` | header 字符类 | 若 header 未变则不动;**status 面板内容不写入 header** |
143
+ | `legion-viz.test.ts` 新增块 | `drawStatus` 单测 | 覆盖 D7 四档宽度 + `w<20` 退化 + inprocess `rss` 为 `—` |
144
+ | `legion-status.test.ts:110-147` | 新增 memory/ctx 行 | 既有首行/`alive`/`execution snapshot` 断言保留,追加新行断言 |
145
+ | `legion-status.test.ts:192-254` | `formatTree` 未变 | **不动**(`formatTree` 不在本契约改动范围) |
146
+
147
+ ## 6. 风险与裁决
148
+
149
+ | 风险 | 裁决 |
150
+ | --- | --- |
151
+ | `drawLog` 内框 `w<=14` 写出 rect 右边界(`panels.ts:530-532`) | **顺手修**:给该 `cv.text` 补 `maxX: r.x + r.w`。属 P2 范围,单独 commit,附回归断言。理由:Worker B 正在改同一文件,且新面板极易复制此模式。**勘误**:`Canvas.text` 的 `maxX` 是**排他上界**(`canvas.ts:39` `if (col >= limit) break`),而 `frame()` 返回的是内框、其右边框列即 `r.x + r.w`,所以「保住最后一个合法内格且不碰边框」的值是 `r.x + r.w`(与 `frame()` / `drawStatus` 一致)。本文早期写的 `r.x + r.w - 1` 会少吃一格,已按 #251 评审改为 `r.x + r.w`。 |
152
+ | view 层 `layout.timing.h - 3` 与 draw 层 `innerH-1-footerH` off-by-one(`view.ts:90`) | **本契约不修**。改动会影响 `timingVisible` 语义与既有断言,独立提 issue。新面板**必须**用精确公式,不照抄 `-3`。 |
153
+ | portrait 零面积 status 被 Tab 跳过 | 由 `availablePanes` 保证;`handleViewKey` 缺省参数保证既有测试不变 |
154
+ | pid 跨进程不可见 | 接受。viz 显示 `—`,不猜。 |
155
+ | `readProcRss` 的 pid 复用 race | **实现为「不打印」**:`!alive` 时直接不读 `/proc`,返回 `undefined`。v1 无 last-known 缓存设施(`memoryLine` 无状态、`TrackedJob` 无 rss 字段),新增缓存需额外的失效规则,比不打印更易说谎。`(last)` 分支**明确不在 v1 范围**。读取必须 try/catch。 |
156
+
157
+ ## 7. 契约修订点
158
+
159
+ - 本文件即新增契约,无需改动 `docs/legion-v2-contract.md` §10.1(三层 UI 定义不变,status 面板属第 2 层内部枚举新增)。
160
+ - `docs/tui-viewer-contract.md:202` 的禁改清单**不包含** `src/tui/viz/**`,Worker B 无需先修订该文档。
161
+ - `README.md` 的「Three-layer visualization」段落可在 P2 后追加一句 status 面板说明(可选,非门禁)。
162
+
163
+ ## 8. 契约勘误(P1 实施中记录)
164
+
165
+ 1. **§5 必改测试表漏列 `test/unit/progress.test.ts`**。D4 的 `progressFromSession` 投影让该文件两处完整对象 `deepEqual` 机械性必红。实际处理:加 `contextTokens: 10` 两行,属**加强断言**(新字段被钉死),零删除。
166
+ 2. **`runtime.test.ts` 既有 D2 测试与 §6 冲突**。该测试原本用 `alive: false` + pid 断言「有 memory 行」,与 pid 复用防护直接矛盾。实际处理:把前置条件改为 `alive: true`,断言文本/正则/非 Linux 分支全部原样保留,强度不变。
167
+ 3. **`(last)` 展示未实现**(见 §6 修订)。
168
+
169
+ ## 9. 修订历史
170
+
171
+ | 日期 | 版本 | 说明 |
172
+ | --- | --- | --- |
173
+ | 2026-10-19 | v1 | 初版。父会话直接裁定(planner 卡死于「声称写文档但从不落盘」,已止损)。 |
174
+ | 2026-10-19 | v1.1 | P1 交付后补:pid 复用裁决改为「不打印」;记录 3 条勘误。 |
@@ -0,0 +1,260 @@
1
+ # 子 agent 续约契约 v1(FROZEN)
2
+
3
+ > 状态:**FROZEN**(2026-10-24 用户提出"能不能加个续约的能力")。
4
+ > 冲突时**停下报告**,不得重新解释本契约。
5
+ > 关联:#270(本契约跟踪号)。
6
+
7
+ ---
8
+
9
+ ## §1 问题陈述
10
+
11
+ 用户原话:
12
+
13
+ > 能不能加个续约的能力,比如上层 agent 看到超时了,可以看看他实际有没有推进,
14
+ > 如果实际推进了,他可以选择续约,让任务继续,而不是丢弃,
15
+ > 不然 worker 的工作浪费了
16
+
17
+ ### 实际发生的事(已确证)
18
+
19
+ 一天之内两次:
20
+
21
+ | 事件 | 结果 |
22
+ |---|---|
23
+ | `W2`(`runtime.ts` 的 D3 投影改造) | 30 分钟耗尽,**零产出落盘** |
24
+ | `W4`(TUI 五文件) | 代码写完,卡在验证/报告;**已找到的编译错误被它自己 revert 掉了**(为了守文件归属纪律) |
25
+
26
+ 两者都不是"做错了",而是**在正确的路径上被切断**。
27
+
28
+ ### 关键事实(侦察确证,带证据)
29
+
30
+ 1. **session 文件完整保留。** `.pi-subagents/runs/r-491ceace/worker-3.jsonl`
31
+ 有 271 行 / 1.4MB,最后一条是 `thinking` —— 说明它是**在思考或工具执行中途**被切断的。
32
+ 2. **续接机制已经存在。** `index.ts:1844-1861` 的 `reviveChild`:
33
+ ```ts
34
+ if (supervisor.isAlive(name)) {
35
+ await orchestrator.steer(name, params.message); // 活着:追加消息
36
+ }
37
+ const handle = await orchestrator.launch({ agent, task, name, ... }); // 死了:复用 session
38
+ // → "Context preserved from <sessionFile>"
39
+ ```
40
+ 3. **两种超时必须区分**(这是 §3 D1 的基础):
41
+ - `wait { timeoutMs }` / `collect { timeoutMs }`(`index.ts:1768`, `:2616`)
42
+ → **父侧放弃等待,不杀 child**。`inprocess-supervisor.ts:1084` 只 `resolve({settled:false, reason:"timeout"})`。
43
+ - 角色 `timeoutMs`(`agents/worker.md:9` 等)
44
+ → 由 **pi 宿主**执行,child 被终止。pi-legion 源码里**没有** `terminated` 这个字面量
45
+ (全仓 grep 只命中 `src/shared/session.ts:912` 的 "terminated during tool call" 文案)。
46
+
47
+ **结论:pi-legion 无法阻止宿主终止 child,但能在终止后识别、评估、续约。** 契约按此边界设计。
48
+
49
+ ---
50
+
51
+ ## §2 根因(为什么现在做不到)
52
+
53
+ ### R1 — 超时终止被当成"失败",没有分类
54
+
55
+ `execution: failed (terminated)` 在展示层与其他失败混在一起。
56
+ 父会话看到的是一条"失败通知",没有"这个 child 被超时切断、其 session 可续"的语义。
57
+
58
+ ### R2 — 没有"推进度"概念
59
+
60
+ 要判断"该不该续约",必须回答"这 30 分钟他是在干活还是卡死"。现有信号分散:
61
+
62
+ | 信号 | 位置 | 能回答 |
63
+ |---|---|---|
64
+ | `lastJsonlEventAgeMs` | `runtime.ts` | 最近一次活动距今多久 |
65
+ | `progressFromSessionFile` | `src/shared/progress.ts` | 解析出的进度摘要 |
66
+ | `NodeActivity{turn,tools,turnStartedAt}` | `runtime.ts` | 第几轮、用过什么工具 |
67
+ | `COLLECT_DEADLINE_REASON` | `orchestrator.ts:280` | 父侧放弃等待(≠ child 死) |
68
+
69
+ 但**没有任何一个**被用来回答"该不该续约"。
70
+
71
+ ### R3 — `wait`/`collect` 超时与 child 终止被混为一谈
72
+
73
+ `inprocess-supervisor.ts:1084` 的超时只表示"我没等到",child 可能还在跑。
74
+ 把它当成 child 失败会导致**错误地重派**(浪费)或**错误地放弃**(丢失)。
75
+
76
+ ---
77
+
78
+ ## §3 决策
79
+
80
+ ### D1 — 只对"真终止 + 有推进"提议续约
81
+
82
+ 续约提议的**必要且充分条件**:
83
+
84
+ ```
85
+ 1. child 确实被终止(不是父侧 wait/collect 超时)
86
+ 2. 自上次续约点以来有可观测推进
87
+ 3. 该角色允许续约(见 D5)
88
+ ```
89
+
90
+ 任一条不满足 → **不提议**,退回现有行为。
91
+
92
+ **理由**:无推进的续约只是把卡死延长一个预算周期,还占着并发槽。
93
+ 这正是角色 `timeoutMs` 存在的意义。
94
+
95
+ ### D2 — 推进度用"产出信号",不用"存活时间"
96
+
97
+ **判据(按可靠度)**:
98
+
99
+ | 优先级 | 信号 | 判读 |
100
+ |---|---|---|
101
+ | 1 | session JSONL 中**新增**的 `toolResult` 行数 | 真做事的最强证据(工具有返回) |
102
+ | 2 | session JSONL 中**新增**的 `assistant` 消息数 | 有产出(写了代码/报告) |
103
+ | 3 | 文件系统副作用(工作树内改动数) | 直接证据,但读盘贵 |
104
+ | 4 | `lastJsonlEventAgeMs` 变小 | **不采用**:只说明有 token 流动 |
105
+
106
+ **明确排除**:进程存活、CPU 时间、token 消耗 —— 这些在"卡在一个失败循环里"时同样增长。
107
+
108
+ **阈值**(D2-a,2026-10-24 父会话裁决,修订本节初稿):
109
+ - 自上次续约点起,新增 **`toolResult` 行数 ≥ 3** → 视为有推进
110
+ - 或工作树内新增/修改文件 ≥ **1** → 视为有推进
111
+ - `assistant` 消息**只统计展示,不参与判定**
112
+
113
+ **为什么只有 toolResult 计数、assistant 不计数**:初稿写的是「`toolResult` + `assistant`
114
+ 合计 ≥ 3」,但 `assistant` 在死循环里会无限增长 —— 模型反复说同一句话也算 "推进",
115
+ 而那恰恰是最需要**不**续约的情形。`toolResult` 意味着**一个工具真的返回了**,是
116
+ "世界被操作过"的证据。因此 assistant 计数保留(给用户看"他产出了多少"),但
117
+ `progressed` 只由 toolResult 与文件改动决定。
118
+
119
+ **为什么是 3**:一次工具调用往返(call + result)+ 一次重试,才够说明"在推进而不是
120
+ 卡在第一次失败上"。1 或 2 会把"刚开工就超时"与"稳步推进"混为一谈。
121
+
122
+ ### D3 — 续约是**显式选择**,不是自动行为
123
+
124
+ **禁止**自动续约。理由:
125
+ - 自动续约会让"卡死"变成"无限占槽",失去预算的约束力
126
+ - 用户/父会话必须能看见"这个 child 卡了 30 分钟,但确实在推进"这个事实再决定
127
+
128
+ **形式**:超时通知里附带**结构化续约提议**:
129
+
130
+ ```
131
+ ✗ W2 (worker) failed: terminated — turn budget exhausted (30m)
132
+ progressed: 47 tool results, 12 assistant messages, 6 files changed since spawn
133
+ resume: subagent({ action: "continue", name: "W2", message: "<what to continue>" })
134
+ ```
135
+
136
+ 即:**给出判断依据 + 现成的命令**,让父会话/用户一条命令就能续。
137
+
138
+ ### D4 — 续约就是 `continue`,不新造机制
139
+
140
+ **禁止**新增 `renew`/`extend` action。续约 = `subagent({action:"continue", name, message})`。
141
+
142
+ 理由:
143
+ - `reviveChild`(`index.ts:1844`)已经实现"复用 session 继续",语义完全匹配
144
+ - 新增 action 会分裂两条等价路径,违反单一事实来源
145
+
146
+ **契约要求的是**:让父会话知道**什么时候值得**发这条命令,并把命令**准备好**。
147
+
148
+ ### D5 — 角色可声明是否允许续约
149
+
150
+ 新增 frontmatter 字段 `renewable`(可选,默认 `true`):
151
+
152
+ ```yaml
153
+ # agents/worker.md
154
+ renewable: true # 默认;超时且有推进时提议续约
155
+ renewable: false # 例如 scout:侦察任务超时说明范围没切好,续约是浪费
156
+ ```
157
+
158
+ **理由**:侦察类角色超时通常意味着任务本身定义有误(范围太大),
159
+ 续约只是把错误延后;而实现类角色超时往往是工程量估计不足,续约是对的。
160
+
161
+ ### D5-a — 如何区分「超时终止」与「正常结束后的 continue」(2026-10-24 父会话裁决)
162
+
163
+ `continue`/`resume` 对所有已终态的 child 都可用,但**只有被预算切断的**才该消耗续约额度。
164
+ 否则「正常失败了、我重试一次」也会吃掉额度,额度就失去意义。
165
+
166
+ **判据(依可靠度排序,取第一个可用者)**:
167
+
168
+ | 优先级 | 判据 | 位置 | 说明 |
169
+ |---|---|---|---|
170
+ | 1 | `execution.stopReason === "toolUse"` | `src/shared/session.ts:912` | **在工具调用中被切断** — 预算耗尽的典型形状 |
171
+ | 2 | 缺 assistant message("missing reply") | `session.ts:12-13`(F29) | hard kill 不写任何 assistant 行 |
172
+ | 3 | `execution.reason` 含 `terminated` | `session.ts:912` | 宿主标注 |
173
+
174
+ **依据**:`src/shared/session.ts:1-14` 的文件头已经把这套语义测过并写死:
175
+
176
+ ```text
177
+ F29 — "aborted" is never actually written. A graceful interrupt (esc) writes
178
+ error + an errorMessage containing "aborted". A hard kill writes NO
179
+ assistant message at all, so "missing reply" IS the abort signal.
180
+ ```
181
+
182
+ 即:**被切断的会话在 JSONL 里是可辨识的**,不需要额外记账。
183
+ `shouldRecycleAfterCollect`(`runtime.ts:226`)只区分「终态/非终态」,**不足以**做这个判断。
184
+
185
+ **`stopReason === "stop"` 或 `"length"`** 的正常结束 → 计额度**不**消耗(用户主动重试)。
186
+
187
+ ### D6 — 续约预算上限
188
+
189
+ 单个 child 的累计续约次数上限 `maxRenewals`(可选,默认 **2**,`0` 表示禁用续约)。
190
+
191
+ 理由:给两次重来机会足以覆盖"估计不足",超过则说明任务切分有问题。
192
+ 每次续约获得一个**完整**的角色 `timeoutMs`(不累计、不递减)。
193
+
194
+ **满额后**:通知里不再提议,改为明确说明"已达续约上限,请重新切分任务"。
195
+
196
+ ### D7 — `wait`/`collect` 超时**绝不**提议续约
197
+
198
+ 见 R3。父侧等待超时 ≠ child 失败。此时正确做法是继续 `wait` 或 `collect`
199
+ (child 还活着),不是续约。
200
+
201
+ **验收**:断言这两个超时路径不产生续约提议。
202
+
203
+ ### D8 — 推进度基线在续约后重置
204
+
205
+ 每次续约成功后,记录新的基线(时间戳 + 当时的行数)。
206
+ 下次超时只统计**自基线以来**的新增。
207
+
208
+ **理由**:防止"总共做过很多事"被误判为"刚刚在推进"。
209
+
210
+ ---
211
+
212
+ ## §4 实施切分
213
+
214
+ | 单元 | 文件 | 内容 |
215
+ |---|---|---|
216
+ | **W1** | `src/runs/progress-signal.ts`(新) | D2 推进度测量:纯函数 + 可注入的文件读取器 |
217
+ | **W2** | `src/shared/types.ts`, `src/agents/{agents,overrides}.ts` | D5 `renewable` + D6 `maxRenewals` 字段解析与默认值 |
218
+ | **W3** | `src/extension/notify.ts`, `src/extension/runtime.ts` | D3 结构化续约提议渲染(仅超时终止路径)+ D7 排除 wait/collect 超时 |
219
+ | **W4** | `index.ts` | D8 基线记录 + 续约计数 + 满额后的文案 |
220
+ | **W5** | `docs/`, `CHANGELOG.md`, `agents/*.md` | 文档与角色默认值 |
221
+
222
+ **文件归属(禁止越界)**:每个 W 只能改自己那一行的文件。
223
+
224
+ ---
225
+
226
+ ## §5 验收
227
+
228
+ | 编号 | 断言 | 归属 |
229
+ |---|---|---|
230
+ | **A1** | 超时终止 + 有推进 + `renewable` → 通知含续约提议与 `continue` 命令 | W3 |
231
+ | **A2** | 超时终止 + **无**推进 → 不提议(续约只是延长卡死) | W1+W3 |
232
+ | **A3** | `wait`/`collect` 超时(child 仍活)→ **不**提议续约(D7) | W3 |
233
+ | **A4** | `renewable: false` 的角色超时 → 不提议 | W2+W3 |
234
+ | **A5** | 续约计数达 `maxRenewals` → 不再提议,文案改为"请重新切分" | W4 |
235
+ | **A6** | 续约成功后基线重置:仅统计新增,不把历史算进推进度(D8) | W4 |
236
+ | **A10** | 正常 `stopReason: "stop"` 后的 `continue` **不**消耗续约额度;`toolUse` 切断才消耗(D5-a) | W4 |
237
+ | **A7** | 推进度阈值:新增 **3 个 toolResult** 或 1 个文件改动为界;assistant 单独不越线(D2-a) | W1 |
238
+ | **A8** | `renew`/`extend` action **不存在**;续约只走 `continue`(D4) | W3 |
239
+
240
+ ---
241
+
242
+ ## §6 迁移影响
243
+
244
+ | 影响 | 处置 |
245
+ |---|---|
246
+ | 现有角色文件缺 `renewable` | 默认 `true`,无需改动 |
247
+ | 超时通知文案变化 | `notify.ts` 现有测试需复核;**只增不改**(保留原有行) |
248
+ | `maxRenewals` 计数存放位置 | 写入 `ChildRecord`(父 run.json),不写账本(与 #266 D3 一致) |
249
+
250
+ ---
251
+
252
+ ## §7 禁令
253
+
254
+ 1. **禁止**自动续约(D3)。
255
+ 2. **禁止**新增 `renew`/`extend` action(D4)。
256
+ 3. **禁止**用"进程存活/CPU 时间/token 消耗"判断推进(D2)。
257
+ 4. **禁止**在 `wait`/`collect` 超时路径提议续约(D7)。
258
+ 5. **禁止**让续约累计超过 `maxRenewals`(D6)。
259
+ 6. **禁止**把续约计数写进账本(§6)。
260
+ 7. **禁止**因续约而改变角色 `timeoutMs` 本身的语义(每次续约是新的完整预算,不是递增)。
@@ -33,9 +33,12 @@ applicable decision for the child cwd:
33
33
 
34
34
  **Ops:** to load project settings / project extensions in an RPC child, either
35
35
  `/trust` that cwd first (writes trust.json) or set `defaultProjectTrust=always`.
36
- This matters most when `inheritExtensions: true` (or
37
- `PI_LEGION_CHILD_INHERIT_EXTENSIONS`) re-enables discovery; the default
38
- `--no-extensions` already blocks most silent project-extension loads.
36
+ Children inherit host extensions by default (4.0.1), so this matters more than
37
+ it used to: a child loads the parent's discovered extensions unless the card
38
+ subtracts them. Note the two axes are different — inheritance is about *which
39
+ extensions*, trust is about whether a *project* may contribute any at all. A
40
+ child's `--no-extensions` still blocks pi's own project-extension discovery, and
41
+ the inherited list is passed explicitly as `--extension` paths.
39
42
 
40
43
  ### Opt-in `--approve` (legion settings)
41
44
 
@@ -1,38 +1,48 @@
1
1
  # In-process AgentSession mode (#197)
2
2
 
3
- Default backend for children. **In-process by default**, with an automatic `rpc`
4
- fallback when the resolved spawn needs an OS worktree (`worktree: true`, which
5
- only a `centurion` can hold — #214). An explicit
6
- `spawnMode: "inprocess"` combined with `worktree: true` is still **refused**
7
- with `INVALID_PARAMS` — the fallback only covers the implicit default.
3
+ Default backend for children. **In-process by default**, with `rpc` used when
4
+ the launch needs an OS worktree (`worktree: true`, which only a `centurion` can
5
+ hold — #214).
6
+
7
+ There is no `spawnMode` config field. The backend is derived from the launch:
8
+
9
+ | Launch needs a worktree? | Backend |
10
+ | --- | --- |
11
+ | no | in-process |
12
+ | yes | `rpc` |
13
+
14
+ Since only a `centurion` may hold a worktree, only a centurion can reach
15
+ `rpc`; every other role is in-process. A non-centurion card that asks for
16
+ `worktree: true` is demoted to `worktree: false` with a once-per-run warning,
17
+ which also keeps it in-process.
8
18
 
9
19
  ## When to use
10
20
 
21
+ The choice is not per-role — it follows from whether the work needs a worktree.
22
+
11
23
  | Mode | Good for | Avoid when |
12
24
  |---|---|---|
13
- | `inprocess` (default; auto-fallback below) | Short, trusted fan-out; lower spawn latency; simpler approval / UI fan-in | Need OS worktree, separate credentials, crash isolation |
14
- | `rpc` (fallback: worktree / non-pi kind; or explicit `spawnMode: rpc`) | Long runs, untrusted tasks, need crash / env / cwd isolation, **worktree** | Cold-start cost dominates |
25
+ | `inprocess` | Short, trusted fan-out; lower spawn latency; simpler approval / UI fan-in | Need OS worktree, separate credentials, crash isolation |
26
+ | `rpc` | Long runs, untrusted tasks, need crash / env / cwd isolation, **worktree** | Cold-start cost dominates |
15
27
 
16
- There is no single global default in the config sense: omitting `spawnMode`
17
- means "inprocess if this role can run in-process, otherwise rpc". Roles that
18
- resolve to `worktree: true` therefore resolve to `rpc` unless they opt out of
19
- the worktree — and since #214 that is only `centurion`: every other role is
20
- downgraded to `worktree: false` with a one-time warning, so it stays
21
- in-process.
28
+ Both backends enforce the same legion tree budgets (`maxDepth` /
29
+ `maxChildrenPerNode` / `maxActiveNodes`); the `subagents.inprocess.*` pools apply
30
+ on top and the stricter gate wins.
22
31
 
23
32
  **Non-goals:** no OS worktree isolation; no promise of process crash containment; OpenAaaS Go in-process transport is out of scope.
24
33
 
25
34
  ## Config
26
35
 
27
- Per agent (frontmatter → `agentOverrides` → team member override):
36
+ There is no `spawnMode` key to configure — not in frontmatter, not in
37
+ `agentOverrides`. The old field was removed (4.0.1); a card that still declares
38
+ it is now rejected at load time, because unknown frontmatter is a hard error.
28
39
 
29
40
  ```yaml
30
41
  # agents/scout.md
31
42
  ---
32
43
  name: scout
33
44
  description: Fast read-only recon
34
- spawnMode: inprocess # omit = inprocess (only a centurion resolves to a worktree, hence rpc)
35
- worktree: false # explicit inprocess + worktree: true is still refused
45
+ worktree: false # a non-centurion asking for true is demoted + warned
36
46
  ---
37
47
  ```
38
48
 
@@ -40,7 +50,7 @@ worktree: false # explicit inprocess + worktree: true is still refused
40
50
  {
41
51
  "subagents": {
42
52
  "agentOverrides": {
43
- "scout": { "spawnMode": "inprocess" }
53
+ "scout": { "worktree": false }
44
54
  },
45
55
  "inprocess": {
46
56
  "maxSpawnsPerSession": 32,
@@ -62,10 +72,79 @@ worktree: false # explicit inprocess + worktree: true is still refused
62
72
  | Concurrent alive | `legion.maxActiveNodes` | `inprocess.maxActive` (default **30**; **8** when the block is present without `maxActive`) |
63
73
  | Children / node | `legion.maxChildrenPerNode` | `inprocess.maxChildrenPerNode` (default **8**) |
64
74
  | Wait timeout | agent `timeoutMs` / wait default | `inprocess.waitTimeoutMs` (no default) |
75
+ | Queue depth | `inprocess.maxQueuedLaunches` (shared by both paths) | `inprocess.maxQueuedLaunches` (default **32**) |
76
+ | Queue wait | `inprocess.launchQueueTimeoutMs` (shared by both paths) | `inprocess.launchQueueTimeoutMs` (default **900000** = 15 min) |
65
77
 
66
78
  Never fall back across columns: in-process limits are read from
67
79
  `subagents.inprocess.*` only, never from the `legion.*` keys.
68
80
 
81
+ ### Renewing a budget casualty (#270)
82
+
83
+ An agent's `timeoutMs` is enforced by the host, so pi-legion cannot prevent the
84
+ cut — but it can make the loss recoverable. When a child is terminated **and**
85
+ it measurably progressed, the completion notice ends with a ready-made command:
86
+
87
+ ```
88
+ ✗ W2 (worker) failed (terminated during tool call)
89
+ progressed: 47 tool results, 12 assistant messages, 6 files changed
90
+ renew: subagent({ action: "continue", name: "W2", message: "<what to continue>" })
91
+ renewals: 1/2
92
+ ```
93
+
94
+ Renewal is `continue` — there is no separate action — so the child resumes from
95
+ its own session file with its context intact. It is **never automatic**: an
96
+ auto-renewed stuck child would hold a concurrency slot indefinitely.
97
+
98
+ Two role frontmatter keys control it:
99
+
100
+ | Key | Default | Meaning |
101
+ |---|---|---|
102
+ | `renewable` | `true` | `false` for roles where a timeout means the task was mis-scoped (a timed-out `scout` is a search that was too broad, not work to finish) |
103
+ | `maxRenewals` | `2` | `0` disables renewal. Each renewal is a **fresh full budget**, never an increment |
104
+
105
+ "Progressed" means ≥ 3 new `toolResult` rows or ≥ 1 changed file since the last
106
+ baseline — `assistant` messages are shown but never count: a model looping on the
107
+ same sentence grows that counter without doing any work. With no progress the
108
+ notice says so instead of offering the command, and once the budget is spent it
109
+ tells you to split the task.
110
+
111
+ `wait`/`collect` timeouts never produce a proposal: those return while the child
112
+ is still alive, which is the opposite situation.
113
+
114
+ ### Launch admission queue (#266)
115
+
116
+ A launch that hits a **queueable** gate waits in an in-memory queue instead of
117
+ throwing `BUDGET_EXCEEDED`, and is admitted automatically when a slot frees. The
118
+ caller gets `▶ scout-7 (scout) supervisor=inprocess queued(3)` back immediately
119
+ and treats the work as dispatched.
120
+
121
+ | Gate | Queued? | Why |
122
+ |---|---|---|
123
+ | `inprocess.maxChildrenPerNode` | ✅ | pure concurrency: the slot always frees |
124
+ | `inprocess.maxActive` | ✅ | same |
125
+ | `legion.maxChildrenPerNode` (`max_children_per_node`) | ✅ | same, RPC path |
126
+ | `legion.maxActiveNodes` (`max_active_nodes`) | ✅ | same, RPC path |
127
+ | `maxDepth` / `maxSpawnsPerSession` / ledger `max_depth` | ❌ | waiting cannot satisfy them; a queue would disguise a permanent failure as a 15-minute delay |
128
+ | `maxChildrenPerNode: 0` | ❌ | 0 means "no children at all" — impossible to satisfy |
129
+ | `parent_not_found`, memory gate, `NAME_TAKEN`, unknown/disabled role, `inprocess`+`worktree`, model scope | ❌ | not a concurrency gate |
130
+
131
+ The two queue bounds are **shared** by both backends on purpose: one scheduler,
132
+ not one per spawn mode. Overflow is an immediate hard refusal
133
+ (`launch queue overflow (32/32)`), a timeout is reported as
134
+ `launch queue timed out after Ns ('<name>')`, and **neither ever creates a
135
+ ledger row, a run directory, a worktree or a session file** — a queued launch has
136
+ reserved nothing yet.
137
+
138
+ Admission is event-driven (a child reaching `retired`/`exited` frees its slot)
139
+ with one `unref`'d fallback recheck, because the ledger can also be freed by
140
+ another process. An `idle` child (turn ended, not yet collected) **still holds
141
+ its slot**, exactly as before.
142
+
143
+ Known limit: the queue is in memory, so a process restart drops it. The leftover
144
+ `queued` records in `run.json` are inert — `collect`/`steer` on one says
145
+ `never started: the launch queue was lost …` instead of `unknown child`, and
146
+ `stop` cleans it up.
147
+
69
148
  Omitting an `inprocess.*` key is **not** unlimited. The documented defaults
70
149
  mirror `legion.*`, so a deployment with no `subagents.inprocess` block at all
71
150
  still runs under `maxDepth: 4` / `maxChildrenPerNode: 8` / `maxActive: 30`.
@@ -83,8 +162,9 @@ a read-only child's write bans, and a parent read-only role wrongly banned a
83
162
  `writer` child.
84
163
 
85
164
  So in-process identity travels in an `AsyncLocalStorage` child context instead:
86
- node id, db path, acceptance role, `allowNested`, `utility`, `spawnMode`, and
87
- the nested parent path. The guards and the legion runtime read that context, and
165
+ node id, db path, acceptance role, `allowNested`, `utility`, `spawnMode` (the
166
+ arbitrated backend, for self-reporting), the per-child `budget`, and the nested
167
+ parent path. The guards and the legion runtime read that context, and
88
168
  only fall back to env for RPC children, whose process really does own its env.
89
169
 
90
170
  Two consequences worth knowing:
@@ -107,8 +187,8 @@ Do not replace this with env injection for in-process children.
107
187
  ```
108
188
  Orchestrator
109
189
  → RoutingSupervisor (LegionSupervisor)
110
- ├─ spawnMode rpc → RpcSupervisor (unchanged)
111
- └─ spawnMode inprocess → InProcessSupervisor
190
+ ├─ worktree ⇒ rpc → RpcSupervisor (unchanged)
191
+ └─ otherwise → InProcessSupervisor
112
192
  createAgentSession + SessionManager.inMemory
113
193
  (tools / model / systemPrompt wired)
114
194
  ```
@@ -187,15 +267,14 @@ a decode rate.
187
267
 
188
268
  ## Refusals
189
269
 
190
- - `kind !== "pi"` → `INVALID_PARAMS` regardless of `spawnMode`: only `pi` roles
191
- are supported, so a non-`pi` role is refused up front and never reaches the
192
- worktree fallback
193
- - `worktree: true` + explicit `inprocess` → `INVALID_PARAMS` (an omitted
194
- `spawnMode` falls back to `rpc` instead)
195
270
  - A non-centurion requesting `worktree: true` is **not** a refusal: it is
196
271
  downgraded to `worktree: false` with a one-time warning (#214), so the launch
197
272
  proceeds in-process. `worktree` is reserved for `centurion`.
198
- - Invalid `spawnMode` string → loud throw at settings / frontmatter parse
273
+ - `worktree: true` reaching the supervisor with a pinned in-process backend →
274
+ `INVALID_PARAMS`. Unreachable from a card now that the field is gone; kept as
275
+ the last line against an internal caller building that shape.
276
+ - Unknown frontmatter (including a leftover `spawnMode:`) → loud throw at parse
277
+ time
199
278
 
200
279
  ## Tests
201
280