pi-legion 4.0.0 → 5.0.0

package/docs/contracts/declarative-phase-machine-v5.md

@@ -0,0 +1,128 @@
+# Declarative phase machine (v5)
+
+Status: draft, layer 3 (#298).
+
+## Problem
+
+The legion phase machine is hard-coded in three places that must agree:
+
+| Place | Hard-codes |
+| --- | --- |
+| `src/legion/state-machine.ts:1` | The seven phase names and every transition rule |
+| `src/agents/settings.ts:117` | A duplicate copy of the phase names, for `phaseTimeouts` validation |
+| `src/extension/legion-tools.ts:47` | The `legion_phase` tool's `to` enum |
+
+Worse, the *rules inside a phase* are keyed on **role names**:
+
+```text
+implementing → reviewing   requires every `role === "worker"` to be settled
+reviewing    → verifying   requires a settled `role === "reviewer"` with verdict ok:true
+planning     → implementing requires no `role === "planner"` still running
+```
+
+So a team cannot re-shape its workflow without editing source, and a role that
+merely *exists* acquires workflow meaning. "worker" is not "a worker" — it is a
+specific slot in a fixed pipeline.
+
+## Goal
+
+A centurion declares its team's phases and the conditions for leaving them.
+Defaults preserve today's behaviour exactly, so an undeclared machine is the
+four-phase pipeline above.
+
+## Non-goals
+
+- Arbitrary scripting. Conditions are a closed vocabulary of predicates, not code.
+- Per-node machines. One machine per team root; children inherit it read-only.
+- Changing how children are spawned. Phases gate *progress*, not dispatch.
+
+## Where the declaration lives
+
+Role frontmatter, on the team root card:
+
+```yaml
+---
+name: centurion
+phases:
+  - id: planning
+    require: [contract_file]
+    next: [implementing]
+    timeoutMs: 900000
+  - id: implementing
+    require: [children_settled]
+    next: [reviewing, failed]
+  - id: reviewing
+    require: [verdict_ok]
+    next: [verifying, implementing]
+  - id: verifying
+    require: [verification_passed]
+    next: [done]
+---
+```text
+
+Kept on the card rather than in `settings` because the machine is a property of
+*this team*, like its roster — two centurions in one settings file may run
+different workflows.
+
+Resolution order: card `phases` → `settings.legion.phases` → built-in default.
+
+## Condition vocabulary
+
+A condition answers "may this node leave phase X for phase Y?" over a snapshot of
+the node and its children. Closed set, each with one meaning:
+
+| Condition | True when |
+| --- | --- |
+| `contract_file` | `contract_path` is set and the file exists and is non-empty |
+| `children_settled` | every child of this node is terminal (settled/failed/retired) |
+| `children_none_failed` | no child is `failed`, or every failed child is listed in `handled` |
+| `verdict_ok` | some settled child's last turn parsed to `{ok: true}` |
+| `verdict_not_ok` | some settled child's last turn parsed to `{ok: false}` |
+| `verification_passed` | the node's stored verification result is `pass` |
+| `verification_failed` | the node's stored verification result is `fail` |
+| `rework_available` | `rework_count < maxRework` |
+| `children_all_failed` | there is ≥1 child and all are `failed` |
+| `always` | unconditional |
+
+`require` is a conjunction: all listed conditions must hold.
+`next` is the allowed successor set; a transition to anything outside it is
+refused with `invalid_transition`.
+
+**Role names do not appear anywhere.** `verdict_ok` asks "did any settled child
+return ok:true", not "did the reviewer". That is what lets `worker` become a
+general worker.
+
+## Terminal phases
+
+Exactly three are terminal and are always available regardless of `next`:
+
+- `done` — only when the phase's `require` holds
+- `failed` — parent decision, all children failed, or rework exhausted
+- `aborted` — parent retire only
+
+## Safety rails (unchanged)
+
+These are invariants, not configuration:
+
+- A new team starts in the machine's **first** phase.
+- `rework_count` still caps at `maxRework` (default 2).
+- `centurion`-only gates stay: a child cannot advance the team.
+- Phase timeouts still only *report*; they never kill work.
+- A declared machine is validated at load time. Unknown condition, empty `next`,
+  duplicate id, unreachable phase, or a terminal phase used as a start → the card
+  is rejected (same posture as unknown frontmatter).
+
+## Migration
+
+The default machine reproduces today's table, so no behaviour change without a
+declaration. The role-name predicates become condition predicates:
+
+| Old rule | New condition |
+| --- | --- |
+| all `worker` settled before reviewing | `children_settled` |
+| settled `reviewer` with ok:true | `verdict_ok` |
+| no `planner` still running | covered by `children_settled` |
+| verification pass before done | `verification_passed` |
+
+Once this lands, `planner` and `reviewer` stop being load-bearing and their
+bundled cards can be deleted.

package/docs/contracts/subagent-renewal-v1.md

@@ -0,0 +1,260 @@
+# 子 agent 续约契约 v1（FROZEN）
+
+> 状态：**FROZEN**（2026-10-24 用户提出"能不能加个续约的能力"）。
+> 冲突时**停下报告**，不得重新解释本契约。
+> 关联：#270（本契约跟踪号）。
+
+---
+
+## §1 问题陈述
+
+用户原话：
+
+> 能不能加个续约的能力，比如上层 agent 看到超时了，可以看看他实际有没有推进，
+> 如果实际推进了，他可以选择续约，让任务继续，而不是丢弃，
+> 不然 worker 的工作浪费了
+
+### 实际发生的事（已确证）
+
+一天之内两次：
+
+| 事件 | 结果 |
+|---|---|
+| `W2`（`runtime.ts` 的 D3 投影改造） | 30 分钟耗尽，**零产出落盘** |
+| `W4`（TUI 五文件） | 代码写完，卡在验证/报告；**已找到的编译错误被它自己 revert 掉了**（为了守文件归属纪律） |
+
+两者都不是"做错了"，而是**在正确的路径上被切断**。
+
+### 关键事实（侦察确证，带证据）
+
+1. **session 文件完整保留。** `.pi-subagents/runs/r-491ceace/worker-3.jsonl`
+   有 271 行 / 1.4MB，最后一条是 `thinking` —— 说明它是**在思考或工具执行中途**被切断的。
+2. **续接机制已经存在。** `index.ts:1844-1861` 的 `reviveChild`：
+   ```ts
+   if (supervisor.isAlive(name)) {
+       await orchestrator.steer(name, params.message);   // 活着：追加消息
+   }
+   const handle = await orchestrator.launch({ agent, task, name, ... });  // 死了：复用 session
+   // → "Context preserved from <sessionFile>"
+   ```
+3. **两种超时必须区分**（这是 §3 D1 的基础）：
+   - `wait { timeoutMs }` / `collect { timeoutMs }`（`index.ts:1768`, `:2616`）
+     → **父侧放弃等待，不杀 child**。`inprocess-supervisor.ts:1084` 只 `resolve({settled:false, reason:"timeout"})`。
+   - 角色 `timeoutMs`（`agents/worker.md:9` 等）
+     → 由 **pi 宿主**执行，child 被终止。pi-legion 源码里**没有** `terminated` 这个字面量
+     （全仓 grep 只命中 `src/shared/session.ts:912` 的 "terminated during tool call" 文案）。
+
+**结论：pi-legion 无法阻止宿主终止 child，但能在终止后识别、评估、续约。** 契约按此边界设计。
+
+---
+
+## §2 根因（为什么现在做不到）
+
+### R1 — 超时终止被当成"失败"，没有分类
+
+`execution: failed (terminated)` 在展示层与其他失败混在一起。
+父会话看到的是一条"失败通知"，没有"这个 child 被超时切断、其 session 可续"的语义。
+
+### R2 — 没有"推进度"概念
+
+要判断"该不该续约"，必须回答"这 30 分钟他是在干活还是卡死"。现有信号分散：
+
+| 信号 | 位置 | 能回答 |
+|---|---|---|
+| `lastJsonlEventAgeMs` | `runtime.ts` | 最近一次活动距今多久 |
+| `progressFromSessionFile` | `src/shared/progress.ts` | 解析出的进度摘要 |
+| `NodeActivity{turn,tools,turnStartedAt}` | `runtime.ts` | 第几轮、用过什么工具 |
+| `COLLECT_DEADLINE_REASON` | `orchestrator.ts:280` | 父侧放弃等待（≠ child 死） |
+
+但**没有任何一个**被用来回答"该不该续约"。
+
+### R3 — `wait`/`collect` 超时与 child 终止被混为一谈
+
+`inprocess-supervisor.ts:1084` 的超时只表示"我没等到"，child 可能还在跑。
+把它当成 child 失败会导致**错误地重派**（浪费）或**错误地放弃**（丢失）。
+
+---
+
+## §3 决策
+
+### D1 — 只对"真终止 + 有推进"提议续约
+
+续约提议的**必要且充分条件**：
+
+```
+1. child 确实被终止（不是父侧 wait/collect 超时）
+2. 自上次续约点以来有可观测推进
+3. 该角色允许续约（见 D5）
+```
+
+任一条不满足 → **不提议**，退回现有行为。
+
+**理由**：无推进的续约只是把卡死延长一个预算周期，还占着并发槽。
+这正是角色 `timeoutMs` 存在的意义。
+
+### D2 — 推进度用"产出信号"，不用"存活时间"
+
+**判据（按可靠度）**：
+
+| 优先级 | 信号 | 判读 |
+|---|---|---|
+| 1 | session JSONL 中**新增**的 `toolResult` 行数 | 真做事的最强证据（工具有返回） |
+| 2 | session JSONL 中**新增**的 `assistant` 消息数 | 有产出（写了代码/报告） |
+| 3 | 文件系统副作用（工作树内改动数） | 直接证据，但读盘贵 |
+| 4 | `lastJsonlEventAgeMs` 变小 | **不采用**：只说明有 token 流动 |
+
+**明确排除**：进程存活、CPU 时间、token 消耗 —— 这些在"卡在一个失败循环里"时同样增长。
+
+**阈值**（D2-a，2026-10-24 父会话裁决，修订本节初稿）：
+- 自上次续约点起，新增 **`toolResult` 行数 ≥ 3** → 视为有推进
+- 或工作树内新增/修改文件 ≥ **1** → 视为有推进
+- `assistant` 消息**只统计展示，不参与判定**
+
+**为什么只有 toolResult 计数、assistant 不计数**：初稿写的是「`toolResult` + `assistant`
+合计 ≥ 3」，但 `assistant` 在死循环里会无限增长 —— 模型反复说同一句话也算 "推进"，
+而那恰恰是最需要**不**续约的情形。`toolResult` 意味着**一个工具真的返回了**，是
+"世界被操作过"的证据。因此 assistant 计数保留（给用户看"他产出了多少"），但
+`progressed` 只由 toolResult 与文件改动决定。
+
+**为什么是 3**：一次工具调用往返（call + result）+ 一次重试，才够说明"在推进而不是
+卡在第一次失败上"。1 或 2 会把"刚开工就超时"与"稳步推进"混为一谈。
+
+### D3 — 续约是**显式选择**，不是自动行为
+
+**禁止**自动续约。理由：
+- 自动续约会让"卡死"变成"无限占槽"，失去预算的约束力
+- 用户/父会话必须能看见"这个 child 卡了 30 分钟，但确实在推进"这个事实再决定
+
+**形式**：超时通知里附带**结构化续约提议**：
+
+```
+✗ W2 (worker) failed: terminated — turn budget exhausted (30m)
+  progressed: 47 tool results, 12 assistant messages, 6 files changed since spawn
+  resume: subagent({ action: "continue", name: "W2", message: "<what to continue>" })
+```
+
+即：**给出判断依据 + 现成的命令**，让父会话/用户一条命令就能续。
+
+### D4 — 续约就是 `continue`，不新造机制
+
+**禁止**新增 `renew`/`extend` action。续约 = `subagent({action:"continue", name, message})`。
+
+理由：
+- `reviveChild`（`index.ts:1844`）已经实现"复用 session 继续"，语义完全匹配
+- 新增 action 会分裂两条等价路径，违反单一事实来源
+
+**契约要求的是**：让父会话知道**什么时候值得**发这条命令，并把命令**准备好**。
+
+### D5 — 角色可声明是否允许续约
+
+新增 frontmatter 字段 `renewable`（可选，默认 `true`）：
+
+```yaml
+# agents/worker.md
+renewable: true     # 默认；超时且有推进时提议续约
+renewable: false    # 例如 scout：侦察任务超时说明范围没切好，续约是浪费
+```
+
+**理由**：侦察类角色超时通常意味着任务本身定义有误（范围太大），
+续约只是把错误延后；而实现类角色超时往往是工程量估计不足，续约是对的。
+
+### D5-a — 如何区分「超时终止」与「正常结束后的 continue」（2026-10-24 父会话裁决）
+
+`continue`/`resume` 对所有已终态的 child 都可用，但**只有被预算切断的**才该消耗续约额度。
+否则「正常失败了、我重试一次」也会吃掉额度，额度就失去意义。
+
+**判据（依可靠度排序，取第一个可用者）**：
+
+| 优先级 | 判据 | 位置 | 说明 |
+|---|---|---|---|
+| 1 | `execution.stopReason === "toolUse"` | `src/shared/session.ts:912` | **在工具调用中被切断** — 预算耗尽的典型形状 |
+| 2 | 缺 assistant message（"missing reply"） | `session.ts:12-13`（F29） | hard kill 不写任何 assistant 行 |
+| 3 | `execution.reason` 含 `terminated` | `session.ts:912` | 宿主标注 |
+
+**依据**：`src/shared/session.ts:1-14` 的文件头已经把这套语义测过并写死：
+
+```text
+F29 — "aborted" is never actually written. A graceful interrupt (esc) writes
+      error + an errorMessage containing "aborted". A hard kill writes NO
+      assistant message at all, so "missing reply" IS the abort signal.
+```
+
+即：**被切断的会话在 JSONL 里是可辨识的**，不需要额外记账。
+`shouldRecycleAfterCollect`（`runtime.ts:226`）只区分「终态/非终态」，**不足以**做这个判断。
+
+**`stopReason === "stop"` 或 `"length"`** 的正常结束 → 计额度**不**消耗（用户主动重试）。
+
+### D6 — 续约预算上限
+
+单个 child 的累计续约次数上限 `maxRenewals`（可选，默认 **2**，`0` 表示禁用续约）。
+
+理由：给两次重来机会足以覆盖"估计不足"，超过则说明任务切分有问题。
+每次续约获得一个**完整**的角色 `timeoutMs`（不累计、不递减）。
+
+**满额后**：通知里不再提议，改为明确说明"已达续约上限，请重新切分任务"。
+
+### D7 — `wait`/`collect` 超时**绝不**提议续约
+
+见 R3。父侧等待超时 ≠ child 失败。此时正确做法是继续 `wait` 或 `collect`
+（child 还活着），不是续约。
+
+**验收**：断言这两个超时路径不产生续约提议。
+
+### D8 — 推进度基线在续约后重置
+
+每次续约成功后，记录新的基线（时间戳 + 当时的行数）。
+下次超时只统计**自基线以来**的新增。
+
+**理由**：防止"总共做过很多事"被误判为"刚刚在推进"。
+
+---
+
+## §4 实施切分
+
+| 单元 | 文件 | 内容 |
+|---|---|---|
+| **W1** | `src/runs/progress-signal.ts`（新） | D2 推进度测量：纯函数 + 可注入的文件读取器 |
+| **W2** | `src/shared/types.ts`, `src/agents/{agents,overrides}.ts` | D5 `renewable` + D6 `maxRenewals` 字段解析与默认值 |
+| **W3** | `src/extension/notify.ts`, `src/extension/runtime.ts` | D3 结构化续约提议渲染（仅超时终止路径）+ D7 排除 wait/collect 超时 |
+| **W4** | `index.ts` | D8 基线记录 + 续约计数 + 满额后的文案 |
+| **W5** | `docs/`, `CHANGELOG.md`, `agents/*.md` | 文档与角色默认值 |
+
+**文件归属（禁止越界）**：每个 W 只能改自己那一行的文件。
+
+---
+
+## §5 验收
+
+| 编号 | 断言 | 归属 |
+|---|---|---|
+| **A1** | 超时终止 + 有推进 + `renewable` → 通知含续约提议与 `continue` 命令 | W3 |
+| **A2** | 超时终止 + **无**推进 → 不提议（续约只是延长卡死） | W1+W3 |
+| **A3** | `wait`/`collect` 超时（child 仍活）→ **不**提议续约（D7） | W3 |
+| **A4** | `renewable: false` 的角色超时 → 不提议 | W2+W3 |
+| **A5** | 续约计数达 `maxRenewals` → 不再提议，文案改为"请重新切分" | W4 |
+| **A6** | 续约成功后基线重置：仅统计新增，不把历史算进推进度（D8） | W4 |
+| **A10** | 正常 `stopReason: "stop"` 后的 `continue` **不**消耗续约额度；`toolUse` 切断才消耗（D5-a） | W4 |
+| **A7** | 推进度阈值：新增 **3 个 toolResult** 或 1 个文件改动为界；assistant 单独不越线（D2-a） | W1 |
+| **A8** | `renew`/`extend` action **不存在**；续约只走 `continue`（D4） | W3 |
+
+---
+
+## §6 迁移影响
+
+| 影响 | 处置 |
+|---|---|
+| 现有角色文件缺 `renewable` | 默认 `true`，无需改动 |
+| 超时通知文案变化 | `notify.ts` 现有测试需复核；**只增不改**（保留原有行） |
+| `maxRenewals` 计数存放位置 | 写入 `ChildRecord`（父 run.json），不写账本（与 #266 D3 一致） |
+
+---
+
+## §7 禁令
+
+1. **禁止**自动续约（D3）。
+2. **禁止**新增 `renew`/`extend` action（D4）。
+3. **禁止**用"进程存活/CPU 时间/token 消耗"判断推进（D2）。
+4. **禁止**在 `wait`/`collect` 超时路径提议续约（D7）。
+5. **禁止**让续约累计超过 `maxRenewals`（D6）。
+6. **禁止**把续约计数写进账本（§6）。
+7. **禁止**因续约而改变角色 `timeoutMs` 本身的语义（每次续约是新的完整预算，不是递增）。

package/docs/headless-child-contract.md

@@ -33,9 +33,12 @@ applicable decision for the child cwd:
 
 **Ops:** to load project settings / project extensions in an RPC child, either
 `/trust` that cwd first (writes trust.json) or set `defaultProjectTrust=always`.
-This matters most when `inheritExtensions: true` (or
-`PI_LEGION_CHILD_INHERIT_EXTENSIONS`) re-enables discovery; the default
-`--no-extensions` already blocks most silent project-extension loads.
+Children inherit host extensions by default (4.0.1), so this matters more than
+it used to: a child loads the parent's discovered extensions unless the card
+subtracts them. Note the two axes are different — inheritance is about *which
+extensions*, trust is about whether a *project* may contribute any at all. A
+child's `--no-extensions` still blocks pi's own project-extension discovery, and
+the inherited list is passed explicitly as `--extension` paths.
 
 ### Opt-in `--approve` (legion settings)
 

package/docs/inprocess-supervisor.md

@@ -1,38 +1,48 @@
 # In-process AgentSession mode (#197)
 
-Default backend for children. **In-process by default**, with an automatic `rpc`
-fallback when the resolved spawn needs an OS worktree (`worktree: true`, which
-only a `centurion` can hold — #214). An explicit
-`spawnMode: "inprocess"` combined with `worktree: true` is still **refused**
-with `INVALID_PARAMS` — the fallback only covers the implicit default.
+Default backend for children. **In-process by default**, with `rpc` used when
+the launch needs an OS worktree (`worktree: true`, which only a `centurion` can
+hold — #214).
+
+There is no `spawnMode` config field. The backend is derived from the launch:
+
+| Launch needs a worktree? | Backend |
+| --- | --- |
+| no | in-process |
+| yes | `rpc` |
+
+Since only a `centurion` may hold a worktree, only a centurion can reach
+`rpc`; every other role is in-process. A non-centurion card that asks for
+`worktree: true` is demoted to `worktree: false` with a once-per-run warning,
+which also keeps it in-process.
 
 ## When to use
 
+The choice is not per-role — it follows from whether the work needs a worktree.
+
 | Mode | Good for | Avoid when |
 |---|---|---|
-| `inprocess` (default; auto-fallback below) | Short, trusted fan-out; lower spawn latency; simpler approval / UI fan-in | Need OS worktree, separate credentials, crash isolation |
-| `rpc` (fallback: worktree; or explicit `spawnMode: rpc`) | Long runs, untrusted tasks, need crash / env / cwd isolation, **worktree** | Cold-start cost dominates |
+| `inprocess` | Short, trusted fan-out; lower spawn latency; simpler approval / UI fan-in | Need OS worktree, separate credentials, crash isolation |
+| `rpc` | Long runs, untrusted tasks, need crash / env / cwd isolation, **worktree** | Cold-start cost dominates |
 
-There is no single global default in the config sense: omitting `spawnMode`
-means "inprocess if this role can run in-process, otherwise rpc". Roles that
-resolve to `worktree: true` therefore resolve to `rpc` unless they opt out of
-the worktree — and since #214 that is only `centurion`: every other role is
-downgraded to `worktree: false` with a one-time warning, so it stays
-in-process.
+Both backends enforce the same legion tree budgets (`maxDepth` /
+`maxChildrenPerNode` / `maxActiveNodes`); the `subagents.inprocess.*` pools apply
+on top and the stricter gate wins.
 
 **Non-goals:** no OS worktree isolation; no promise of process crash containment; OpenAaaS Go in-process transport is out of scope.
 
 ## Config
 
-Per agent (frontmatter → `agentOverrides` → team member override):
+There is no `spawnMode` key to configure — not in frontmatter, not in
+`agentOverrides`. The old field was removed (4.0.1); a card that still declares
+it is now rejected at load time, because unknown frontmatter is a hard error.
 
 ```yaml
 # agents/scout.md
 ---
 name: scout
 description: Fast read-only recon
-spawnMode: inprocess   # omit = inprocess (only a centurion resolves to a worktree, hence rpc)
-worktree: false        # explicit inprocess + worktree: true is still refused
+worktree: false        # a non-centurion asking for true is demoted + warned
 ---
 ```
 
@@ -40,7 +50,7 @@ worktree: false        # explicit inprocess + worktree: true is still refused
 {
   "subagents": {
     "agentOverrides": {
-      "scout": { "spawnMode": "inprocess" }
+      "scout": { "worktree": false }
     },
     "inprocess": {
       "maxSpawnsPerSession": 32,
@@ -68,6 +78,39 @@ worktree: false        # explicit inprocess + worktree: true is still refused
 Never fall back across columns: in-process limits are read from
 `subagents.inprocess.*` only, never from the `legion.*` keys.
 
+### Renewing a budget casualty (#270)
+
+An agent's `timeoutMs` is enforced by the host, so pi-legion cannot prevent the
+cut — but it can make the loss recoverable. When a child is terminated **and**
+it measurably progressed, the completion notice ends with a ready-made command:
+
+```
+✗ W2 (worker) failed (terminated during tool call)
+progressed: 47 tool results, 12 assistant messages, 6 files changed
+renew: subagent({ action: "continue", name: "W2", message: "<what to continue>" })
+renewals: 1/2
+```
+
+Renewal is `continue` — there is no separate action — so the child resumes from
+its own session file with its context intact. It is **never automatic**: an
+auto-renewed stuck child would hold a concurrency slot indefinitely.
+
+Two role frontmatter keys control it:
+
+| Key | Default | Meaning |
+|---|---|---|
+| `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) |
+| `maxRenewals` | `2` | `0` disables renewal. Each renewal is a **fresh full budget**, never an increment |
+
+"Progressed" means ≥ 3 new `toolResult` rows or ≥ 1 changed file since the last
+baseline — `assistant` messages are shown but never count: a model looping on the
+same sentence grows that counter without doing any work. With no progress the
+notice says so instead of offering the command, and once the budget is spent it
+tells you to split the task.
+
+`wait`/`collect` timeouts never produce a proposal: those return while the child
+is still alive, which is the opposite situation.
+
 ### Launch admission queue (#266)
 
 A launch that hits a **queueable** gate waits in an in-memory queue instead of
@@ -119,8 +162,9 @@ a read-only child's write bans, and a parent read-only role wrongly banned a
 `writer` child.
 
 So in-process identity travels in an `AsyncLocalStorage` child context instead:
-node id, db path, acceptance role, `allowNested`, `utility`, `spawnMode`, and
-the nested parent path. The guards and the legion runtime read that context, and
+node id, db path, acceptance role, `allowNested`, `utility`, `spawnMode` (the
+arbitrated backend, for self-reporting), the per-child `budget`, and the nested
+parent path. The guards and the legion runtime read that context, and
 only fall back to env for RPC children, whose process really does own its env.
 
 Two consequences worth knowing:
@@ -143,8 +187,8 @@ Do not replace this with env injection for in-process children.
 ```
 Orchestrator
     → RoutingSupervisor (LegionSupervisor)
-         ├─ spawnMode rpc        → RpcSupervisor   (unchanged)
-         └─ spawnMode inprocess  → InProcessSupervisor
+         ├─ worktree ⇒ rpc       → RpcSupervisor   (unchanged)
+         └─ otherwise            → InProcessSupervisor
                                       createAgentSession + SessionManager.inMemory
                                       (tools / model / systemPrompt wired)
 ```
@@ -223,12 +267,14 @@ a decode rate.
 
 ## Refusals
 
-- `worktree: true` + explicit `inprocess` → `INVALID_PARAMS` (an omitted
-  `spawnMode` falls back to `rpc` instead)
 - A non-centurion requesting `worktree: true` is **not** a refusal: it is
   downgraded to `worktree: false` with a one-time warning (#214), so the launch
   proceeds in-process. `worktree` is reserved for `centurion`.
-- Invalid `spawnMode` string → loud throw at settings / frontmatter parse
+- `worktree: true` reaching the supervisor with a pinned in-process backend →
+  `INVALID_PARAMS`. Unreachable from a card now that the field is gone; kept as
+  the last line against an internal caller building that shape.
+- Unknown frontmatter (including a leftover `spawnMode:`) → loud throw at parse
+  time
 
 ## Tests
 

package/docs/legion-v2-contract.md

@@ -3,6 +3,15 @@
 > 状态：**FROZEN-1**（2026-10-11 CEO 批准冻结；修订必须走 §15 流程）
 > 依据：2026-10-10/11 军团需求对齐（侦察底稿：`r-584dd563` scout-0/scout-1、`r-20cc52a2` scout-2，共 226 条带行号事实；RPC/SQLite/浮窗三项本机实测通过）
 > 修订规则：见 §15。worker 发现契约矛盾时**停下上报**，禁止自行解释。
+>
+> **阅读须知（2026-10-26）**：本文是 v2 的冻结快照，保留原样作为历史依据。
+> 其中三处已被后续实现取代：一是 §7 的「四阶段状态机 + 按角色名判定迁移」，
+> 已改为每队声明式状态机、按条件判定（`children_settled` / `verdict_ok` …），
+> 不再出现角色名（#298）；二是术语表与架构图里的「组员：scout/worker/reviewer…」，
+> 现只内置 `centurion` / `worker` / `scout`（#301）；三是「每个子节点都是
+> RpcClient 进程」，默认已是进程内 `AgentSession`，只有持 worktree 的 centurion
+> 走 rpc（#279）。
+> 现行行为以 `README.md` 与 `docs/contracts/declarative-phase-machine-v5.md` 为准。
 
 ---
 

package/docs/spawn-mode-visibility-v1.md

@@ -25,7 +25,10 @@ Facts established by recon (do not re-verify):
 ## D1 — Wording (backend-neutral) for parent guidance
 
 Children are **in-process by default**; a separate `pi` process is used only when
-the launch needs a worktree (centurion) or the role pins `spawnMode: rpc`.
+the launch needs a worktree — and since only a centurion may hold one, only a
+centurion reaches `rpc`. (The `spawnMode` role field described here was removed
+in 4.0.1; `handle.spawnMode` below remains the arbitrated backend and is still
+what callers must render.)
 
 Replace "RPC child / headless RPC children / started via RPC / RPC launch" with
 backend-neutral phrasing in these exact places: