pi-legion 3.0.0 → 3.0.3

package/docs/design.md

@@ -219,18 +219,48 @@ launch (async) ──→ 子 pane 跑
        │
        ├─ TUI：输入框上方 aboveEditor widget（live agent 面板）
        │        （pi-subagents fleet-status；footer 不再重复计数，见 #192）
-       └─ collect 在后台等 turn 结束
+       └─ collect 在后台等 run 结束
               │
-              └─ pi.sendMessage({ customType: "subagent-notify" },
-                    { triggerTurn: true, deliverAs: "followUp" })
-                 父会话空闲则立刻唤醒；若父会话还在跑当前 turn（工具循环），
-                 等这一轮结束后再投递，避免 steer 打断正在干的事。
-                 所有状态都 display:true（transcript 留下完成/失败记录）；
-                 成功由 notice-renderer 压成单行并按 pane 宽度硬截断
-                 （控制字符已消毒，ctrl+o 展开），
-                 失败/中止保留完整块，details 只供 TUI 不进 LLM 上下文。
+              └─ runtime 完成通道（唯一的延迟源，按 **run** 级判定）
 ```
 
+完成通知的投递分两段，**只有一处 run 级延迟**：join 窗口是纯批处理延迟，二者串行叠加
+（最坏串联约 10s + 80s）——除此之外不存在第二个"等父会话忙完"的延迟源。
+
+1. **join 批处理窗口**（`src/extension/join.ts`，默认 10s）：同一 runId 的多个 child
+   一起启动、先后结束，窗口把 straggler 合成一条消息（`Background tasks completed
+   (N of M)`）。窗口**只做批处理**，到期无条件 flush 到下一个环节，**不**因为父会话忙
+   而延长——turn 级的 busy 是错误预测器（工具循环里父会话按定义就是忙的），而且会在
+   outbox 之外叠加第二层延迟。
+2. **run 级 outbox**（`src/extension/runtime.ts`，`MAX_PENDING_AGE_MS = 80_000`）：
+   父 **run** 活跃时不 `pi.sendMessage`，通知入 FIFO 队列；`agent_settled` 到达后
+   一次性 burst 发出（一条通知一条消息），并重绘 UI。硬上限 80s（= 2× 旧的
+   `(1+3)×10s`）到点强制发送并计入 `noticeQueueStats().forcedFlushes`，宁可回到旧
+   行为也不无限隐藏。父 run 不活跃时**立即**发送（含 `mode: "each"`、单成员批次、
+   `triggerTurn:false` 项）。
+
+   上限是 **per-notice** 而不是 per-run：到点判定用 notice 自己的 `enqueuedAt` 算
+   （`runtime.ts` 的 `armOutboxTimer` 从 `outbox[0]` 起算，
+   `noticeQueueStats().oldestAgeMs` 也报最老一条）。所以父 run 持续 10 分钟时，不是
+   给整个 run 记一个 80s 预算、也不是因为 run 还在跑就无限顺延：队列里最老一条到点就
+   触发（`flushOutbox` 一次 `splice(0)`，连同队列里更年轻的 notice 一起按 FIFO burst
+   发出）。T3d 把「arm 与 oldestAgeMs 都跟最老一条」钉成测试。
+
+为什么不能只发 `followUp`：宿主只在 **live run 内部** drain `agent.followUpQueue`，
+所以父 run 活跃时发出去的 followUp 会一直躺在队列里，直到用户再发一条消息才出现。
+这正是「完成通知看起来没来」的根因。发送时形状不变——
+`pi.sendMessage({ customType: "subagent-notify" }, { triggerTurn: true, deliverAs: "followUp" })`
+——只是**时机**改到 run 结束时。
+
+所有状态都 display:true（transcript 留下完成/失败记录）；
+成功由 notice-renderer 压成单行并按 pane 宽度硬截断
+（控制字符已消毒，ctrl+o 展开），
+失败/中止保留完整块，details 只供 TUI 不进 LLM 上下文。
+
+> print/json 模式：`session_shutdown` → `dispose()` 丢弃未投递的 pending。child 的
+> session 文件仍在，可用 `collect` 从磁盘恢复；但 `finished` 缓存**不**保留
+> （`dispose()` 开头就 `jobs.clear()` / `finished.clear()`，此后才丢弃 outbox）。
+
 父 agent 的正确用法：`subagent` 工具 launch 之后把控制权交回用户，等 completion
 message，而不是轮询，也不是让孩子来拍自己。
 

package/docs/inprocess-supervisor.md

@@ -1,8 +1,8 @@
 # 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`, the
-writer/centurion default). An explicit
+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.
 
@@ -15,8 +15,10 @@ with `INVALID_PARAMS` — the fallback only covers the implicit default.
 
 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
-default to `worktree: true` (writer, centurion) therefore resolve to `rpc`
-unless they opt out of the worktree.
+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.
 
 **Non-goals:** no OS worktree isolation; no promise of process crash containment; OpenAaaS Go in-process transport is out of scope.
 
@@ -29,7 +31,7 @@ Per agent (frontmatter → `agentOverrides` → team member override):
 ---
 name: scout
 description: Fast read-only recon
-spawnMode: inprocess   # omit = inprocess (worktree roles auto-fall back to rpc)
+spawnMode: inprocess   # omit = inprocess (only a centurion resolves to a worktree, hence rpc)
 worktree: false        # explicit inprocess + worktree: true is still refused
 ---
 ```
@@ -126,6 +128,63 @@ Production `defaultSessionFactory` calls `createAgentSession` with:
 
 See `buildInProcessSessionPlan` / `test/unit/inprocess-supervisor.test.ts`.
 
+## Observability: live token rate during the first run
+
+`spawnChild` returns as soon as the child **accepts** the first prompt, not when
+that turn ends (#227 D1). Acceptance is read off the child transcript — a user
+line for this turn appearing past the size recorded at spawn time (`F7`: the SDK
+appends the user message before it runs the agent) — with
+`DEFAULT_INPROCESS_SPAWN_START_TIMEOUT_MS` (15s, injectable as
+`spawnStartTimeoutMs`) as a bound that is **not** an error: on expiry the handle
+is still returned and `onSpawnDelayed` is called once. The turn itself keeps
+running on a background drain, inside the child's identity scope.
+
+The one exception is **rejection before acceptance** (#227 D1a): no model, no
+API key, or a compaction in progress makes the SDK throw before it appends the
+user message, so nothing ever lands in the transcript. In that case
+`spawnChild` still **throws** `SubagentError(..., START_FAILED)` and rolls the
+child back rather than returning a handle. That is deliberate: `Orchestrator`
+only retries the next `fallbackModels` entry when the spawn throws
+(`canFallbackStart`), so returning a handle there would silently disable the
+fallback chain. A turn that was accepted and *then* failed stays a runtime
+failure: the handle is returned, `SettleResult.reason` reads
+`child turn failed: …`, and `onSpawnRefused` reports it.
+
+So the *reason* the ledger needs a direct read has changed, but the read is
+still required. Two windows remain uncovered by `statusEntryFromJob`:
+
+1. **Before acceptance** (normally milliseconds, up to the start bound): the
+   launch has not yet written `node_launched` / `recordChild`, so no job exists.
+2. **From acceptance to settle**: the job exists, but its usage columns stay
+   empty until the turn ends — `pollUsage` only samples nodes that are already
+   `running`, and a spawning node is `starting`.
+
+During window 2 the ledger row still carries no live token rate, so the status
+board keeps seeing only the ledger node row. That row must still render a live
+token rate, which needs two facts the ledger does not carry during a run:
+
+| Fact | Ledger during a run | Source used instead |
+|---|---|---|
+| `tokensOut` | empty until settle: `pollUsage` skips nodes whose status is not `running`, and a spawning node is `starting` | `nodes.session_file` parsed directly |
+| `generationMs` | never stored (`usage` has no such column) | same session parse |
+
+Reading `node.sessionFile` stays correct for the same underlying reason as
+before: the transcript is the only live source while the turn runs. What changed
+is that the child is no longer *invisible* to the orchestrator for the whole of
+its first turn — only its **usage ledger** still lags.
+
+`statusEntryFromNode` reads `node.sessionFile` through `progressFromSessionFile`
+for both, falling back to the ledger for nodes with no session file (rebuilt or
+foreign rows). Without this the railway header showed `0 tok/s` for the whole
+in-process lifetime while `rpc` looked correct.
+
+`generationMs` itself is the sum of measured model-call lengths
+(`message.durationMs`, or entry-to-entry write times). It must never be derived
+from the nested `message.timestamp`, which marks when generation *started* and
+yields only prompt-to-first-token latency — that mistake pinned the denominator
+near zero, so `tok/s` silently fell back to a wall-clock window and stopped being
+a decode rate.
+
 ## Refusals
 
 - `kind !== "pi"` → `INVALID_PARAMS` regardless of `spawnMode`: only `pi` roles
@@ -133,6 +192,9 @@ See `buildInProcessSessionPlan` / `test/unit/inprocess-supervisor.test.ts`.
   worktree fallback
 - `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
 
 ## Tests

package/docs/legion-v2-contract.md

@@ -208,7 +208,7 @@ description: 百夫长/组长：携带一支团队递归派生的指挥角色。
 kind: pi
 allowNestedSubagents: true
 maxSubagentDepth: 2          # R=本角色子树代数上限（含自身；与所在深度无关；只收紧不放宽）：1=叶子禁派生；2=可派一层组员、组员不可再派；3=组员（如孙代 centurion）可再派一层
-worktree: true               # 子树 worktree：本人 cwd 即队的工作区（§9）
+worktree: true               # 子树 worktree：本人 cwd 即队的工作区（§9；该权限经 REV-17 收为 centurion 专属）
 team:                        # 可选：默认队（须是 settings.teams 里真实存在的队名）；省略 = 全 roster 可选；launch 可覆盖（subagent({team:"fe-premium"})）
 ---
 ```
@@ -320,7 +320,9 @@ legion_phase({ to, note?, evidence? })                // 仅 centurion（§7）
 
 ## 9. 隔离与交付（子树 worktree、MR 树）
 
-- **per-subtree worktree**：centurion launch 时由**其父**创建（复用现有 `createChildWorktree`：`git worktree add -b pi-subagent/<slug>-<nonce>`，D8 仅 git）；centurion 的 cwd 即该 worktree；**组员一律 `worktree:false` 原地干活**。隔离边界从"每个 writer"上移到"每个子树"，MR 数量从 O(组员数) 降到 O(子树数)
+- **per-subtree worktree**：centurion launch 时由**其父**创建（复用现有 `createChildWorktree`：`git worktree add -b pi-subagent/<slug>-<nonce>`，D8 仅 git）；centurion 的 cwd 即该 worktree；**组员一律 `worktree:false` 原地干活**。隔离边界从"每个 writer"上移到"每个子树"，MR 数量从 O(组员数) 降到 O(子树数)。**N 并行隔离 writer** = 根直派 N 个 centurion（各 1 worktree），centurion 内组员 inprocess；不要给每个 worker 开 worktree
+- **worktree 仅 centurion 可用**（REV-17，#214）：`worktree: true` 是 centurion 角色的专属权限，不存在其他持有者。判定以角色名 `centurion` 为准：centurion 卡一律拿到子树 worktree（嵌套 centurion 拿 nested worktree，不受「父是 centurion ⇒ 组员不隔离」压制）；centurion 的组员一律不拿；其余角色（`worker` / `prototype` / `scout` / `reviewer` / `planner` / `advisor` / `designer`，含用户自建 writer 角色）既不自动获得、也不会因 `acceptance.role: writer` 而获得 worktree
+- **违规处理为降级，不是报错**（REV-17）：非 centurion 角色卡声明 `worktree: true`、或 `subagent({ worktree: true })` 显式传参，一律**降级为 `worktree: false`**，并 `console.warn` 一次（每 Orchestrator 实例一次，同 `depthWarningEmitted` 语义）。**不抛错**——抛错会阻断 launch，而降级的语义是「回到契约本来的边界」；被降级的组员与父共享 checkout，其改动留在父的工作区里
 - 孙代 centurion 在子树 worktree 内再开 nested worktree（git 原生支持），递归成立
 - **MR 树**（D6）：每棵子树一个 squash MR → 父节点（或其队）合并 → 逐级上交 → 根合入默认分支。合并权在各级父节点，叶子永不 merge（现有纪律的递归推广）
 - 文件所有权清单随契约（§7.2）逐层传递；契约矛盾 = 正确拒绝，上报修订后重派
@@ -414,7 +416,7 @@ interface LegionEventBus {
 
 ### M2 军团树（组织层：db + centurion + 状态机 + 邮件）
 
-- **归属**：新增 `src/legion/{db,nodes,events,usage,mail,state-machine,budget,rebuild}.ts`、`agents/centurion.md`、`src/extension/legion-tools.ts`；修改 `orchestrator.ts`（launch 落库/树命名/预算查库/子树 worktree）、`src/runs/worktree.ts`（subtree 模式）、`src/runs/args.ts`（env 增 `PI_LEGION_DB`/`PI_LEGION_NODE_ID`）、`src/agents/agents.ts`、`index.ts`（队级 resume、collect 落库）
+- **归属**：新增 `src/legion/{db,nodes,events,usage,mail,state-machine,budget,rebuild}.ts`、`agents/centurion.md`、`src/extension/legion-tools.ts`；修改 `orchestrator.ts`（launch 落库/树命名/预算查库/子树 worktree——经 REV-17 收为 centurion 专属，非 centurion 请求 warns 一次后降级）、`src/runs/worktree.ts`（subtree 模式）、`src/runs/args.ts`（env 增 `PI_LEGION_DB`/`PI_LEGION_NODE_ID`）、`src/agents/agents.ts`、`index.ts`（队级 resume、collect 落库）
 - **验收**：(a) 三层树 e2e：CEO→centurion→workers×2 全阶段走通（契约落盘→并行实施→review verdict→verify 实跑→done 收队 + squash MR）；(b) rework 循环：review major→回 implementing→复审通过；(c) rework≥2 → failed 上抛；(d) kill centurion 进程 → 孤儿报警 → resume 恢复整队、settled 组员不复活、运行中组员上下文延续；(e) `maxActiveNodes` 超限拒派 + 事件；(f) 邮件：同级/父子/父←子通、跨子树拒发并提示路由、retired 收件人唤醒投递、终态收件人退信；(g) WAL 压测：60 模拟 supervisor 并发写 5 分钟，busy 超时率 <0.1%；(h) `legion-rebuild` 从 run.json+jsonl 重建 nodes/events；(i) 非 pi kind 明确拒绝
 
 ### M3 可视化
@@ -459,3 +461,4 @@ interface LegionEventBus {
 | 2026-10-11 | REV-14 | §10.1 点击双通道降级：OSC 8 超链接仅作视觉锚点（宿主 TUI 截获链接点击去 openBrowser，pi-tui tui-alt-screen.js:1097-1104 + extensions types 无 URL 回调 API——worker-14 读源码实证）；浮窗打开 = 组件鼠标事件 + 键盘路径（/legion <name>）。鼠标事件在全屏模式路由到组件（tree-view 自管分页的点击 handler 已支持），regular 模式无鼠标为宿主限制。触发：worker-14 按 §15-2 正确拒绝（WIP 已由合并权人固化 2dff211） |
 | 2026-10-11 | REV-15 | §6.1 centurion 角色卡的 `team: be-value` 改为可选省略：be-value 是示例值，仓库/用户 settings 均未定义该队，不覆盖时子进程收警告并退化全 roster。team 字段语义 = 可选的默认队绑定（须真实存在），省略即全 roster。触发：reviewer-6 对 PR #13 的范围外观察 |
 | 2026-10-12 | REV-16 | §3.2 retire 链加固：SIGTERM 超时后升级 SIGKILL（新 option `killTimeoutMs`，默认 1s），并在 retire 时枚举子 pi 的后代进程（/proc 祖先链），按进程组 SIGTERM→SIGKILL 清场（排除 supervisor 自身进程组与子 pi 自身 pid）。触发：2026-10-12 孤儿 `node --test` 进程泄露事故（两个 PPID=1 进程各烧 4h20m CPU，SIGTERM 无效，人工 SIGKILL 收场）。子契约：`docs/retire-hardening-contract.md`（FROZEN-1） |
+| 2026-10-19 | REV-17 | §9 worktree 收为 centurion 专属（权限变更，按 §15-4 走修订）：① 判定以角色名 `centurion` 为准，centurion 卡一律拿子树 worktree、嵌套 centurion 拿 nested worktree；② 其余角色一律不拿——删除「`acceptance.role: writer` 自动补 `worktree: true`」的隐式默认，`agents/worker.md` 从 `worktree: true` 改为显式 `worktree: false`（`agents/centurion.md` 的 `true` 与 `agents/prototype.md` 的 `false` 不变）；③ 违规一律**降级为 `false` + `console.warn` 一次**，**不抛错**（抛错会阻断 launch）；`subagent({ worktree: true })` 显式传参同样降级。不改 `resolveLaunchWorktree` 的优先级链（不变式 I5），不新增事件类型，不改 `spawnMode` 仲裁逻辑。原因：issue #214（worktree 收为 centurion 专属，与 §9 已冻结的「组员一律 `worktree: false`」对齐；实现向契约收敛，隔离边界继续由「每棵子树」承载） |

package/docs/subagents-teams.md

@@ -102,12 +102,16 @@ and override semantics.
 ## spawnMode (rpc | inprocess)
 
 Omitted → `inprocess`, with an automatic `rpc` fallback when the resolved spawn
-needs an OS worktree (`worktree: true`, the writer/centurion default). A
-non-`pi` role is rejected before this point, so it never reaches the fallback.
-An explicit `spawnMode: "inprocess"` + `worktree: true` is
-still refused with `INVALID_PARAMS`. Precedence: frontmatter →
+needs an OS worktree (`worktree: true`, which only a `centurion` can hold —
+#214). A non-`pi` role is rejected before this point, so it never reaches the
+fallback. An explicit `spawnMode: "inprocess"` + `worktree: true` is still
+refused with `INVALID_PARAMS`. Precedence: frontmatter →
 `subagents.agentOverrides.<role>` → team member override.
 
+`worktree: true` is centurion-only: any other role that asks for it is
+downgraded to `worktree: false` with a one-time warning, so squad members always
+run in-process in the centurion's subtree worktree.
+
 See [inprocess-supervisor.md](./inprocess-supervisor.md) (#197) for the backend
 details, the separate `subagents.inprocess.*` limits, and the
 AsyncLocalStorage identity channel.

package/docs/vexillatio-contract.md

@@ -54,7 +54,7 @@ const VexillatioParams = Type.Object({
 
 1. 解析 agent：默认 `scout`；目标必须在 catalog 里且 `utility === true`，否则报错 `not a utility agent: <name> (mark it with 'utility: true')`。
 2. 走**既有 `orchestrator.launch`**（复用 budget/session 管线），但 `SpawnInput.env` 显式剔除 legion 身份四变量：`PI_LEGION_DB`、`PI_LEGION_NODE_ID`、`PI_SUBAGENT_PARENT_PATH`、`PI_SUBAGENT_MAX_DEPTH`（防幽灵节点 + 防工具人继承指挥链身份）。**不剔除** `PI_SUBAGENT_CHILD`、`PI_SUBAGENT_CHILD_ROLE`、`PI_SUBAGENT_MAX_TOOL_CALLS` 等预算变量（child-guard 仍要工作）。utility 目标（两通道）**剥除 `PI_SUBAGENT_ALLOW_NESTED`**（§2.5.1，utility 语义优先）；`lineageEnv` 统一设置 `PI_SUBAGENT_UTILITY_CHILD`（§2.2）。
-3. launch 后 `awaitSupervisor` + 静默宽限（复用 `collect` 的 grace 逻辑），产出直接以文本返回（`renderCollect` 简化版：`── <name> ──\nexecution: …\n<output>`），同 `collect` 的 `outputFile` 惯例写 `<name>.output.md`。
+3. launch 后 `awaitSupervisor` + 静默宽限（复用 `collect` 的 grace 逻辑），产出直接以文本返回（`renderCollect` 简化版：`── <name> ──\nexecution: …\n<output>`），同 `collect` 的 `outputFile` 惯例写 `<name>.output.md`。**中断返回语义（REV-17.9）**：父轮结束时（`signal.aborted`）不丢弃已收集的结果——返回文本 = 冻结头行 `interrupted (parent turn ended; children still running)` + 已收集的每一段（顺序 = handles 顺序，含 launch 失败行 `✗ <agent>: <error>`）；`details` 带 `{ runId, handles, async: false, interrupted: true, stillRunning? }`。没有 handle 时文本退化为只有头行 + 失败行，不出现空段；`interruptedCollect` 仍给 `status:"running"` + `reason:"aborted by parent"`，照旧渲染、不改写成 success。
 4. 返回值含 `outputFile`/`sessionFile` 路径，父可后续用 `subagent({action:'collect'|'steer'|'retire', name})` 控制——**节点进 legion 树**， parent = 派发进程自己的 nodeId；无 legion 身份的**child** 派发者走普通 run 目录管线（子记录必须 `store.addChild` 落 run.json，同 launchStep 惯例——REV-17.8 修正：原措辞导致实现只 updateChild 丢记录）；**root** 派发者照 subagent 通道惯例创建 root legion（原措辞含糊，见 REV-17.8 修订记录）。
 
 ### 2.3 env 语义（冻结表）
@@ -160,3 +160,4 @@ const VexillatioParams = Type.Object({
 | 2026-10-12 | REV-17.6 | §2.2/§2.3/§2.5.1/§2.5.3 四处统一：**utility 语义优先，allowNested 被忽略**——两通道对 utility 目标都剥除 ALLOW_NESTED，不存在持有 subagent 的工具人，误配不恢复递归路径（§2.5.1 原句“此时持有 subagent”是 17.4 引入的后门，与硬叶子不变量自相矛盾） | worker-5 指出硬叶子规则与误配时持有 subagent 的规定冲突——拒绝正确，修订后重派 |
 | 2026-10-12 | REV-17.7 | 新增 §2.7 工具白名单注入规则（`pushToolArgs` 对非 utility 角色追加 vexillatio）；§3 新增 `src/runs/args.ts` 所有权 + 两个 `read,bash` 断言授权（orchestrator.test:99 / supervisor.test:265）。分支已合入 master 最新（PR #22） | worker-6 完成全部实现后指出：受限角色（显式 tools: 白名单）调不到未列名的 vexillatio，需在 args 层追加且两个既有断言未授权——拒绝正确；从原会话恢复继续，勿重写已完成的 90% |
 | 2026-10-13 | REV-17.8 | 三路 review 门禁退回后的修复授权：M1=非 legion 派发者子记录持久化（persistChild 改 findChild 守卫式 addChild+updateChild，补集成测试）；M3=package.json 四脚本加 `-u PI_SUBAGENT_UTILITY_CHILD`；测试缺口补：跨通道同名续接（subagent 先派 scout-0 后 vexillatio 应派 scout-1）与超时行为（不 autoSettle 场景）；契约自身修正：§2.2 步骤 4 措辞（child 走 addChild 惯例/root 走 createRootLegion）、rpc-supervisor/types.ts 追认、§3 新增 package.json。四个 minor 采纳：abort signal 贯通、strip 列表常量化、verify 字段报错、child-mode 越授权改动追认；其余 minor（F5 重构收敛等）记档不阻塞 | 四路 reviewer 独立印证 3 major（M1 探针实证 children:[]、M2 部署惰性、M3 32 假失败实测）；采纳 worker-0/2/3 交叉发现 |
+| 2026-10-19 | REV-17.9 | §2.2 步骤 3 补中断返回语义：父轮结束时返回已收集结果 + `details.interrupted`，冻结头行保持逐字（#227 D4） | issue #227 缺陷 2（中断丢弃已收集结果，`index.ts:2416` / `:743-745` 两层丢弃）；`docs/contracts/vexillatio-nonblocking-launch-v1.md` 冻结 |

package/index.ts

@@ -94,6 +94,7 @@ import {
 	type OrchestratorLegionContext,
 } from "./src/runs/orchestrator.ts";
 import { RunStore, pickChildByName } from "./src/runs/store.ts";
+import { RUN_OWNER_FILE, ownerState } from "./src/runs/owner.ts";
 import { resolveLaunchWorktree } from "./src/runs/worktree.ts";
 import {
 	type AgentConfig,
@@ -103,6 +104,7 @@ import {
 	ErrorCodes,
 	type ModelOrigin,
 	type RetireOptions,
+	type SpawnMode,
 	SubagentError,
 	type SubagentsSettings,
 } from "./src/shared/types.ts";
@@ -122,7 +124,7 @@ const TaskItem = Type.Object({
 	worktree: Type.Optional(
 		Type.Boolean({
 			description:
-				"Parent decides isolation for this child. true = own git branch, child opens an MR. false = write the current checkout.",
+				"Parent decides isolation for this child. true = own git branch, child opens an MR. false = write the current checkout. Reserved for `centurion` (#214): any other role asking for true is downgraded to false with a one-time warning.",
 		}),
 	),
 	verify: Type.Optional(
@@ -174,7 +176,7 @@ const SubagentParams = Type.Object({
 	worktree: Type.Optional(
 		Type.Boolean({
 			description:
-				"Parent decides isolation. true = isolated git branch, child opens an MR. false = edit the current checkout. Omit to use the role default (bundled worker: true).",
+				"Parent decides isolation. true = isolated git branch, child opens an MR. false = edit the current checkout. Reserved for `centurion` (#214): only a centurion gets a subtree worktree, every other role is downgraded to false with a one-time warning — dispatch a centurion when you need an isolated delivery unit.",
 		}),
 	),
 	verify: Type.Optional(
@@ -293,6 +295,19 @@ function runStoreFor(cwd: string, dbPathOverride?: string): RunStore {
 	return new RunStore({ rootDir: path.join(cwd, ".pi-subagents") });
 }
 
+/**
+ * Backend THIS process was started on (#209), for `run.json`'s `herdr.supervisor`.
+ *
+ * A host/root session and an RPC child are both ordinary `pi` processes, so the
+ * historic `rpc` marker is the truth for them. An in-process child shares this
+ * process, and its backend travels on the ALS child context — the one case where
+ * the truthful marker is not `rpc`. Reading it from there (instead of writing a
+ * literal) is what stops the record from claiming RPC for an inprocess child.
+ */
+function currentProcessSpawnMode(): SpawnMode {
+	return currentChildContext()?.spawnMode ?? "rpc";
+}
+
 function notice(pi: ExtensionAPI, text: string): void {
 	pi.sendMessage({ customType: SUBAGENT_NOTIFY_TYPE, content: text, display: true }, { triggerTurn: true, deliverAs: "followUp" });
 }
@@ -399,6 +414,9 @@ function resolveLegionIdentity(input: {
 		const nodeRuns = input.store.listRuns().filter((run) => run.nodeId === nodeId || run.herdr.node_id === nodeId);
 		let nodeRun = nodeRuns.at(-1);
 		if (!nodeRun) {
+			// Contract D3: a run synthesized while attaching to an already-existing
+			// node has no launch arbitration behind it, so it keeps the historic
+			// marker instead of inventing a backend.
 			nodeRun = input.store.createRun({ task: node.taskSummary ?? `Resume ${node.role} node ${node.id}`, cwd: input.cwd, path: parseNestedPathEnv(process.env.PI_SUBAGENT_PARENT_PATH), maxDepth: effectiveMaxDepth(input.settings.legion?.maxDepth), nodeId, herdr: { supervisor: "rpc", node_id: nodeId } });
 		}
 		if (node.runId !== nodeRun.runId) updateLegionRunId(db, nodeId, nodeRun.runId);
@@ -442,7 +460,7 @@ async function resumeLegionTeam(input: { identity: LegionRuntimeIdentity; input:
 }
 
 function createRootLegion(input: { pi: ExtensionAPI; supervisor: LegionSupervisor; store: RunStore; cwd: string; task: string; settings: ReturnType<typeof loadSubagentSettings>; maxDepth: number; eventBus: LegionEventBus }): LegionRuntimeIdentity {
-	const rootRun = input.store.createRun({ task: input.task, cwd: input.cwd, maxDepth: input.maxDepth, nodeId: "root", herdr: { supervisor: "rpc" } });
+	const rootRun = input.store.createRun({ task: input.task, cwd: input.cwd, maxDepth: input.maxDepth, nodeId: "root", herdr: { supervisor: currentProcessSpawnMode() } });
 	const dbPath = path.resolve(legionDbPath(input.store.runDir(rootRun.runId)));
 	const db = openLegionDb(dbPath);
 	const now = Date.now();
@@ -722,9 +740,10 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 					},
 					onUtilityChild: (retire) => pendingUtilityRetires.push(retire),
 				});
-				if (signal?.aborted) {
-					return ok("interrupted (parent turn ended; children still running)");
-				}
+				// `launchUtilityFamily` already folds the abort into its own return
+				// (head line + collected segments + `interrupted` details, #227 D4).
+				// Returning `result` unconditionally is what keeps that work visible;
+				// re-checking `signal.aborted` here would throw it away again.
 				return result;
 			},
 		});
@@ -760,10 +779,9 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 	const childActivitySources = new Set<string>();
 	let statusNodeOpener: ((nodeId: string) => void) | undefined;
 	let lastConfirm: ((message: string) => Promise<boolean>) | undefined;
-	// turn_start/turn_end maintain this so a flush window can wait out a
-	// busy parent instead of queueing behind the whole turn (join extends
-	// the window at most MAX_BUSY_EXTENSIONS times).
-	let parentTurnActive = false;
+	// Run-scoped completion deferral lives in the runtime outbox (D-A): a child
+	// finishing while this agent run is still active is held until
+	// `agent_settled` instead of being queued as an undrained followUp.
 	const rpcEventSource = supervisor as LegionSupervisor & RpcEventSource;
 	const runtime = createSessionRuntime({
 		sendMessage: (message, options) => pi.sendMessage(message, options),
@@ -999,7 +1017,6 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 			runtime.setJoinConfig({
 				mode: settings.joinMode ?? DEFAULT_JOIN_MODE,
 				flushMs: settings.joinFlushMs ?? DEFAULT_FLUSH_MS,
-				parentBusy: () => parentTurnActive,
 			});
 
 			if (action === "list") return ok(renderAgentList(agents, team, teamWarnings));
@@ -1175,19 +1192,22 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 	});
 	pi.on("session_info_changed", bindUi);
 	pi.on("turn_start", (event, ctx) => {
-		parentTurnActive = true;
 		bindUi(event, ctx);
 	});
 	pi.on("turn_end", (event, ctx) => {
-		parentTurnActive = false;
 		bindUi(event, ctx);
 	});
 	pi.on("agent_start", (event, ctx) => {
+		runtime.notifyParentRunStart();
 		bindUi(event, ctx);
 	});
 	pi.on("agent_end", (event, ctx) => {
 		bindUi(event, ctx);
 	});
+	pi.on("agent_settled", (event, ctx) => {
+		runtime.notifyParentSettled();
+		bindUi(event, ctx);
+	});
 	pi.on("input", bindUi);
 	pi.on("tool_result", (_event, ctx) => {
 		bindUi(_event, ctx);
@@ -1317,6 +1337,7 @@ async function controlAction(input: {
 		return stopAction({
 			params,
 			runtime: input.runtime,
+			store: input.store,
 			retire: async (name, opts) => {
 				const merged = opts ?? retireOpts;
 				const job = input.runtime.get(name);
@@ -1358,18 +1379,23 @@ async function controlAction(input: {
 			);
 		}
 		if (!params.name) {
-			const live = listLiveChildrenForStatus(store.listRuns());
+			const runs = store.listRuns();
+			const live = listLiveChildrenForStatus(runs);
 			return ok(
 				renderStatusOverview(
-					live.map((child) => ({
-						child,
-						alive: input.supervisor.isAlive(child.name),
-					})),
+					live.map((child) => {
+						const alive = input.supervisor.isAlive(child.name);
+						const owner = ownerVerdictFor(store, runs, child.name, alive);
+						return { child, alive, ...(owner ? { owner } : {}) };
+					}),
 				),
 			);
 		}
-		const found = findChild(store.listRuns(), params.name);
+		const runs = store.listRuns();
+		const found = findChild(runs, params.name);
 		if (!found) return unknownChild(params.name, store, cwd);
+		const alive = input.supervisor.isAlive(params.name);
+		const owner = ownerVerdictFor(store, runs, params.name, alive);
 		return ok(renderLiveChildStatus({
 			name: found.child.name,
 			state: found.child.state,
@@ -1378,7 +1404,9 @@ async function controlAction(input: {
 			sessionFile: found.child.sessionFile,
 			execution: found.child.execution,
 			acceptance: found.child.acceptance,
-			alive: input.supervisor.isAlive(params.name),
+			spawnMode: found.child.spawnMode,
+			alive,
+			...(owner ? { owner } : {}),
 		}));
 	}
 
@@ -1652,7 +1680,7 @@ async function launchFamily(input: {
 			task: plan.task,
 			cwd,
 			maxDepth,
-			...(legion ? { path: parseNestedPathEnv(process.env.PI_SUBAGENT_PARENT_PATH), nodeId: legion.nodeId, herdr: { supervisor: "rpc" as const, node_id: legion.nodeId } } : { herdr: { supervisor: "rpc" as const } }),
+			...(legion ? { path: parseNestedPathEnv(process.env.PI_SUBAGENT_PARENT_PATH), nodeId: legion.nodeId, herdr: { supervisor: currentProcessSpawnMode(), node_id: legion.nodeId } } : { herdr: { supervisor: currentProcessSpawnMode() } }),
 		});
 		if (legion && legion.nodeId !== "root" && legion.parentRunId) {
 			const node = getNode(legion.db, legion.nodeId);
@@ -1919,7 +1947,7 @@ async function launchStep(
 			return;
 		}
 		session.results.push(
-			`▶ ${handle.name} (${effective.name}) supervisor=rpc`,
+			`▶ ${handle.name} (${effective.name}) supervisor=${handle.spawnMode}`,
 		);
 		// An inherited model the target CLI cannot express is dropped on purpose
 		// (the parent's pi model means nothing to cursor). Say so, or the user
@@ -2226,7 +2254,7 @@ async function launchUtilityFamily(input: {
 			cwd: input.cwd,
 			maxDepth: effectiveMaxDepth(catalog.settings.legion?.maxDepth),
 			path: parseNestedPathEnv(process.env.PI_SUBAGENT_PARENT_PATH),
-			herdr: { supervisor: "rpc" },
+			herdr: { supervisor: currentProcessSpawnMode() },
 		});
 	if (!run) return fail("vexillatio parent run is not available", ErrorCodes.NOT_FOUND);
 	const runId = run.runId;
@@ -2386,7 +2414,13 @@ async function launchUtilityFamily(input: {
 			return `✗ ${handle.name}: collect failed: ${error instanceof Error ? error.message : String(error)}\nsessionFile: ${handle.sessionFile}`;
 		}
 	}));
-	if (input.signal?.aborted) return ok("interrupted (parent turn ended; children still running)");
+	if (input.signal?.aborted) return interruptedUtilityResult({
+		runId,
+		handles,
+		stillRunning,
+		results,
+		collected,
+	});
 	results.push(...collected);
 	return {
 		content: [{ type: "text", text: results.join("\n\n") || "No utility agents were launched." }],
@@ -2401,6 +2435,40 @@ async function launchUtilityFamily(input: {
 	};
 }
 
+/**
+ * Build the interrupted vexillatio result from what the collect loop already produced.
+ *
+ * `#227 D4`: an abort must not throw away work that already finished. The frozen
+ * head line stays first and verbatim (`test/unit/teams.test.ts` matches it with a
+ * regex), the collected segments are appended below it, and `details` carries the
+ * same machine facts a non-interrupted return publishes plus `interrupted: true`.
+ *
+ * With no handles (every launch failed) the text degrades to the head line plus
+ * the failure lines only — no empty segment.
+ */
+function interruptedUtilityResult(input: {
+	runId: string;
+	handles: Array<{ name: string; agent: string; sessionFile: string }>;
+	stillRunning: Set<string>;
+	results: string[];
+	collected: string[];
+}): AgentToolResult<unknown> {
+	const head = "interrupted (parent turn ended; children still running)";
+	const segments = [...input.results, ...input.collected].filter((segment) => segment.length > 0);
+	const stillRunning = input.handles
+		.filter(({ name }) => input.stillRunning.has(name))
+		.map(({ name }) => name);
+	// Routed through `ok()` so the widened `details` parameter has exactly one
+	// real consumer instead of being a dead signature (#227 review F3).
+	return ok(segments.length > 0 ? `${head}\n\n${segments.join("\n\n")}` : head, {
+		runId: input.runId,
+		handles: input.handles.map(({ name, agent, sessionFile }) => ({ name, agent, sessionFile })),
+		async: false,
+		interrupted: true,
+		...(stillRunning.length > 0 ? { stillRunning } : {}),
+	});
+}
+
 /**
  * Resolve an explicit `name=` on launch.
  *
@@ -2742,11 +2810,13 @@ export function renderStatusOverview(
 	children: Array<{
 		child: NonNullable<ReturnType<RunStore["findChild"]>>;
 		alive: boolean;
+		/** Run-dir ownership verdict (#209-3); see {@link renderLiveChildStatus}. */
+		owner?: "live" | "dead" | "unknown";
 	}>,
 ): string {
 	if (children.length === 0) return "No live children.";
 	const noun = children.length === 1 ? "child" : "children";
-	const blocks = children.map(({ child, alive }) =>
+	const blocks = children.map(({ child, alive, owner }) =>
 		renderLiveChildStatus({
 			name: child.name,
 			state: child.state,
@@ -2755,7 +2825,9 @@ export function renderStatusOverview(
 			sessionFile: child.sessionFile,
 			execution: child.execution,
 			acceptance: child.acceptance,
+			spawnMode: child.spawnMode,
 			alive,
+			...(owner ? { owner } : {}),
 		}),
 	);
 	return [`Status · ${children.length} live ${noun}`, "", blocks.join("\n\n")].join("\n");
@@ -2882,6 +2954,26 @@ export function renderWait(results: WaitResult[]): string {
 	return parts.join("\n");
 }
 
+/**
+ * Run-dir ownership verdict for a child THIS process does not track (#209-3).
+ *
+ * `supervisor.isAlive` is an in-memory registry of children spawned by this
+ * process, so it is always false for a foreign run (another session, or a
+ * restart). The run dir's `owner.json` pid is the durable liveness marker; it
+ * only needs to be consulted when the in-memory answer is "not alive".
+ */
+function ownerVerdictFor(
+	store: RunStore,
+	runs: ReturnType<RunStore["listRuns"]>,
+	name: string,
+	alive: boolean,
+): "live" | "dead" | "unknown" | undefined {
+	if (alive) return undefined;
+	const picked = pickChildByName(runs, name);
+	if (!picked) return "unknown";
+	return ownerState(path.join(store.runDir(picked.run.runId), RUN_OWNER_FILE));
+}
+
 /**
  * Retire a named child or every child tracked by this session.
  * `force: true` → hard path (graceful:false / SIGTERM→SIGKILL); omit/false → graceful.
@@ -2889,6 +2981,11 @@ export function renderWait(results: WaitResult[]): string {
 export async function stopAction(input: {
 	params: { name?: string; all?: boolean; force?: boolean };
 	runtime: SessionRuntime;
+	/**
+	 * Run store used to resolve a named target this session does not track
+	 * (foreign/restarted runs). Omitted callers keep the runtime-only scope.
+	 */
+	store?: RunStore;
 	retire: (name: string, opts?: RetireOptions) => Promise<void>;
 }): Promise<AgentToolResult<unknown>> {
 	const { params, runtime, retire } = input;
@@ -2906,11 +3003,21 @@ export async function stopAction(input: {
 	if (params.all) {
 		targets = active.map((job) => job.name);
 	} else {
-		const target = jobs.find((job) => job.name === params.name);
+		// Local const so the earlier `name`/`all` guard narrows through the lookup.
+		const name = params.name;
+		const target = name ? jobs.find((job) => job.name === name) : undefined;
 		if (!target) {
-			return fail(`unknown child: ${params.name} (not tracked by this session).`, ErrorCodes.NOT_FOUND);
+			// Not tracked by this session, but a foreign/restarted run may still
+			// own a persisted record — the same records `status` can display. Fall
+			// back to it so stop and retire agree on what is reachable.
+			const found = input.store && name ? findChild(input.store.listRuns(), name) : null;
+			if (!found) {
+				return fail(`unknown child: ${params.name} (not tracked by this session).`, ErrorCodes.NOT_FOUND);
+			}
+			targets = found.child.state === "retired" ? [] : [found.child.name];
+		} else {
+			targets = target.state === "retired" ? [] : [target.name];
 		}
-		targets = target.state === "retired" ? [] : [target.name];
 	}
 	if (targets.length === 0) return ok("No non-retired children to stop.");
 
@@ -3080,34 +3187,6 @@ function findChild(
 	return { runId: picked.run.runId, run: picked.run, child: picked.child };
 }
 
-function renderChild(
-	child: NonNullable<ReturnType<RunStore["findChild"]>>,
-	action: string,
-): AgentToolResult<unknown> {
-	const lines = [
-		`${child.name} — state=${child.state} agent=${child.agent ?? "?"} kind=${child.kind ?? "?"}`,
-		"supervisor=rpc",
-		`session=${child.sessionFile}`,
-	];
-	if (child.execution) {
-		lines.push(
-			`execution: ${child.execution.status}${child.execution.reason ? ` (${child.execution.reason})` : ""}`,
-		);
-		if (child.execution.usage) {
-			lines.push(
-				`usage: in=${child.execution.usage.input} out=${child.execution.usage.output} cost=${child.execution.usage.cost.toFixed(4)}`,
-			);
-		}
-	}
-	if (child.acceptance)
-		lines.push(
-			`acceptance: ${child.acceptance.status} (${child.acceptance.level})`,
-		);
-	if (action === "collect" && !child.execution)
-		lines.push("(not yet collected — call collect while the agent is alive)");
-	return ok(lines.join("\n"));
-}
-
 function renderCollect(
 	name: string,
 	collected: {
@@ -3165,8 +3244,20 @@ function renderCollect(
 	return lines.join("\n");
 }
 
-function ok(text: string): AgentToolResult<unknown> {
-	return { content: [{ type: "text", text }], details: {} };
+/**
+ * Render a success/neutral result to the model.
+ *
+ * `details` defaults to `{}`; callers that already computed machine facts
+ * (runId/handles for an interrupted collect) pass them through instead of
+ * discarding them (#227 D4) — `interruptedUtilityResult` is that caller.
+ * `isError` is deliberately never set — the rendering chain and every assertion
+ * in this repo work without it.
+ */
+function ok(
+	text: string,
+	details: Record<string, unknown> = {},
+): AgentToolResult<unknown> {
+	return { content: [{ type: "text", text }], details };
 }
 
 /**