pi-legion 5.1.0 → 5.2.0

package/CHANGELOG.md

@@ -11,6 +11,35 @@ summary so you can see **2.x vs 0.16** without leaving the tree.
 
 ## [Unreleased]
 
+## [5.2.0] — 2026-11-04
+
+一次以「回复说真话」为中心的发布。批量派发的每个子节点可以带自己的 handle；`stop` 与超时的回复不再把
+「已经跑完」「还在跑」说成相反的东西；`collect` 与 `stop` 撞车时不再丢最后一轮产物；文档里「`timeoutMs`
+会终止子节点」的说法被容器实测推翻并改正。
+
+### Added
+
+- **`tasks[]` 的每个条目现在可以带自己的 `name`，而且这个 handle 一定生效。** 以前条目里的 `name` 被
+  静默丢弃——schema 里没有这个字段、`launchStep` 也从不读它，于是调用方明明写了名字，批量出来的子节点仍被
+  自动编号成 `scout-N`/`worker-N`，没有任何提示；现在条目名优先、其次顶层 `name=`、都没有才自动编号。名字不合
+  语法、同一批内重名（含大小写/空格差异）、或单条目同时给了两个不同的名字，都在**任何子节点启动之前**整批拒绝，
+  不会留下「一半按调用方的名字、一半按自动名」的半启动状态。`vexillatio` 自己为每一步分配唯一 handle，因此对
+  条目里的 `name` 直接报错拒绝，而不是静默忽略。
+
+### Fixed
+
+- **`stop` 的回复现在带状态，不再把「已经跑完」说成「被停掉」。** 名字在子节点 retire 之后才到达时，回复是
+  `No non-retired children to stop. worker-2 is already retired (execution: success, retired at …)`；命中
+  settle→retire 那一小段窗口时，回复 `Retired 1 already-settled child: x (execution: success)` 而不是
+  `Stopped 1 child`——后者等于宣称一次从未发生的打断。retire 行为本身不变，只有措辞。
+
+- **超时不再被说成会终止子节点，`stop` 竞态也不再丢最后一轮产物。** 角色 `timeoutMs` 实际只是父侧等待预算：
+  容器实测 `worker.timeoutMs=10s` 的 child 存活 56s 并正常 `success`，且 pi 1.4 的 CLI / settings 都没有 turn 级超时；
+  文档与 renewal 契约据此改正，`collect deadline (cumulative since launch)` 改为 `(per collect attempt)`（原文案
+  本来就是错的）。`finishCollect` 在「child 已被 retire」时仍写 `<name>.output.md`，不再因 `stop` 撞上 collect
+  而丢掉那一轮文本。失败通知携带 `stopReason` / `errorMessage` / `errorKind`，当合成 reason 表达不了 provider
+  错误时多打一行 `error:`；`wait` 超时回执的 `hint` 改为「只是停止等待，child 还在跑」，不再把 `stop` 摆在建议位。
+
 ## [5.1.0] — 2026-11-02
 
 一次以**可恢复、可声明的子树**为中心的发布。三个新能力：`centurion` 的状态机改为由 root 派发时用 `phases:` 声明（不声明就是普通 agent）；同一个 session 重开能接回上次的树，退出等于暂停、恢复必须显式；长等待中的 `wait`/`collect` 会在收到子节点邮件时立刻返回。`/legion` 一侧：整帧分配降到 2.0MB 以内（120×40 −59%、200×60 −67%），overlay 改为主屏挂载，状态行能说清子节点正在做什么，且不再每写一格分配一个 `Cell`。另有三十余项稳定性修复：失败队不再静默消失、内联相位机器进树、headless 账本不再漏记、`ctx is stale` 与宿主 `turn_end` 的报错消失。

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

@@ -41,10 +41,12 @@
    - `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" 文案）。
+     → **父侧等待预算，不终止 child**（`orchestrator.ts` 的 collect deadline；到点返回 `running`，watch 重新武装）。
+     宿主没有 turn 级超时：pi 1.4 的 CLI / settings 都没有该开关，子进程 argv 也不带 timeout（2026-11 容器实测：
+     `worker.timeoutMs=10s` 的 child 存活 56s 并正常 `success`）。真正终止 child 的只有 `stop`、session shutdown、
+     工具预算切断。
 
-**结论：pi-legion 无法阻止宿主终止 child，但能在终止后识别、评估、续约。** 契约按此边界设计。
+**结论：宿主不会因 `timeoutMs` 终止 child。真正的终止来自 stop / shutdown / 工具预算，pi-legion 无法阻止，但能在终止后识别、评估、续约。** 契约按此边界设计。
 
 ---
 

package/docs/contracts/vexillatio-nonblocking-launch-v1.md

@@ -159,3 +159,4 @@ npm run test:integration
 | 2026-10-19 | v1 | 首次冻结 | #227 三缺陷拆分：D1/D2/D3(A)、D4/D3b/D5(B)；D6/D7 显式排除 |
 | 2026-10-19 | v1.1 | 勘误 §1 D1 轮询常量位置：`src/shared/types.ts` → 实为 `src/runs/orchestrator.ts:143` 私有常量，改由 `src/supervisor/spawn-mode.ts` 导出同值常量；§2 Worker A 文件表同步 | Worker A 指出契约原文事实错误；`grep` 确认 `POLL_INTERVAL_MS` 从未在 `src/shared/types.ts` 出现过。属笔误型而非设计型矛盾，advisor 裁决按勘误继续（不回退重派），父会话在此落库 |
 | 2026-10-19 | v1.2 | 新增 **D1a**：首次 prompt 在「受理之前」reject 时 `spawnChild` 仍须抛出（保 `fallbackModels`）；§3 验收清单同步为 8 条 | 父会话审查 PR #228 实测发现回归：非阻塞改造把受理前 reject 吞成「已 spawn」，`canFallbackStart` 失效。HEAD 抛错 / 首版实现返回 handle，属 #227 之外的回归，必须以先红后绿用例守住 |
+| 2026-11-04 | v1.3 | **D6 复议**：`COLLECT_DEADLINE_REASON` 的 `cumulative since launch` 措辞改为 `per collect attempt`，同步更新 5 个测试文件的字面断言 | 该字面量本来就是错的（deadline 从 collect 调用起算），当初只因「测试钉住了」而冻结；容器实测（role `timeoutMs`=10s 的 child 存活 56s 并 success）证明它不是 kill 预算，留错字面会继续误导排障 |

package/docs/contracts/wait-not-stop.md

@@ -14,7 +14,7 @@ result includes structured fields for the **parent** to decide:
 - `status`: `wait_timeout` | `still_running` | `budget_exceeded` (budget optional)
 - `done` / `stillRunning[{ name, elapsedMs, budgetMs? }]`
 - `decisions`: `extend` | `steer_again` | `stop` | `force_stop` (model hint enum, not a new RPC)
-- `hint`: wait does not stop children; choose stop/force_stop or extend/steer
+- `hint`: wait only stopped waiting — the children are still running and keep their context; prefer `status`/`extend`/`steer_again`, and use `stop`/`force_stop` only to abandon the work
 
 The parent then calls existing tools (`wait` again, `steer`, or `stop` with
 optional `force: true`). Tooling must not auto-SIGKILL on timeout.

package/docs/design.md

@@ -928,7 +928,10 @@ subagent({
 
   // launch
   agent?: string, task?: string,
-  tasks?: Array<{ agent: string; task: string }>,   // 并行
+  tasks?: Array<{ agent: string; task: string; name?: string }>,   // 并行
+                            // name 是该条目自己的 handle（批量内必须互不相同，
+                            // 省略则由 launch 自动编号 role-N）；单条目时也可
+                            // 用顶层 name=，两处给不同值会被拒
   async?: boolean,          // 默认 true
   model?: string, cwd?: string, placement?: string,
   worktree?: boolean,       // 隔离 git worktree（默认随角色）

package/docs/inprocess-supervisor.md

@@ -80,9 +80,15 @@ Never fall back across columns: in-process limits are read from
 
 ### 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:
+An agent's `timeoutMs` is the parent's **wait** budget, not a kill switch: when
+it elapses, `collect`/`wait` stop waiting and report `running`, and the child
+keeps running (the watch re-arms). Nothing in pi or pi-legion terminates a child
+at that deadline — verified against pi 1.4: no CLI flag, no settings key, and no
+timeout is passed in a child's argv.
+
+A child is terminated by an explicit `stop`, by session shutdown, or by a
+tool-call budget cut. When that happens **and** it measurably progressed, the
+completion notice ends with a ready-made command:
 
 ```
 ✗ W2 (worker) failed (terminated during tool call)

package/docs/vexillatio-contract.md

@@ -51,7 +51,11 @@ const VexillatioParams = Type.Object({
 });
 ```
 
-**只有 launch 语义**（无 status/collect/wait/steer/retire——用 `subagent` 工具的既有控制动作管理同名子节点；见 2.6）。执行流程（同步）：
+**只有 launch 语义**（无 status/collect/wait/steer/retire——用 `subagent` 工具的既有控制动作管理同名子节点；见 2.6）。
+
+**先于下列步骤的前置校验**：`tasks[]` 条目带 `name` → 硬拒（`INVALID_PARAMS`），消息为 ``tasks[] step <i> cannot include `name`; vexillatio allocates one handle per step itself.``。命名权归 vexillatio（§2.6 `<role>-N` 接续父节点既有 children），接受该字段等于把「调用方指定的 handle 静默失效」搬进工具人通道。
+
+执行流程（同步）：
 
 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）。

package/index.ts

@@ -61,7 +61,7 @@ import { appendEvent, maxEventId } from "./src/legion/events.ts";
 import { attachUsageTotals, upsertUsage } from "./src/legion/usage.ts";
 import { getChildByName, getChildren, getNode, getSubtree, insertNode, isTerminalNode, LIVE_CHILD_STATUSES, type LegionNode, updateNode } from "./src/legion/nodes.ts";
 import { markSessionInterrupted } from "./src/legion/interrupt.ts";
-import { type LegionSettings } from "./src/shared/types.ts";
+import { type ExecutionStatus, type LegionSettings } from "./src/shared/types.ts";
 import { parseNestedPathEnv } from "./src/shared/nested-path.ts";
 import { allocateSiblingNames, isValidAgentName } from "./src/shared/name.ts";
 import {
@@ -247,6 +247,12 @@ void phaseMachineSchemaParity;
 const TaskItem = Type.Object({
 	agent: Type.String({ description: "Name of the agent to invoke" }),
 	task: Type.String({ description: "Task to delegate" }),
+	name: Type.Optional(
+		Type.String({
+			description:
+				"Explicit handle for THIS child (same grammar as the top-level `name`: [a-z][a-z0-9_-]{0,31}). Omit to auto-allocate `<role>-N`. Every handle in one tasks[] batch must be distinct. A one-entry batch may name its child here or at the call level, but not two different values. `vexillatio` allocates names itself and refuses this field.",
+		}),
+	),
 	cwd: Type.Optional(
 		Type.String({
 			description:
@@ -288,7 +294,7 @@ const SubagentParams = Type.Object({
 				Type.Literal("stop"),
 				Type.Literal("diagnose"),
 			],
-			{ description: "Defaults to launch. wait REQUIRES name or all:true (mutually exclusive) — bare wait is rejected. diagnose = Legion doctor self-check (extensions/models/spawn/memory/tools/storage/runtime); optional section filters like /legion doctor." },
+			{ description: "Defaults to launch. wait REQUIRES name or all:true (mutually exclusive) — bare wait is rejected. A `stop` that reaches a child which already finished reports it as `already retired` / `Retired … already-settled` (nothing was interrupted), not as a failed stop. diagnose = Legion doctor self-check (extensions/models/spawn/memory/tools/storage/runtime); optional section filters like /legion doctor." },
 		),
 	),
 	agent: Type.Optional(
@@ -3677,7 +3683,7 @@ interface LaunchSession {
  */
 async function launchStep(
 	session: LaunchSession,
-	step: { agent: string; task: string; model?: string; preset?: string; worktree?: boolean; verify?: string[] },
+	step: { agent: string; task: string; name?: string; model?: string; preset?: string; worktree?: boolean; verify?: string[] },
 ): Promise<void> {
 	if (session.signal?.aborted) return;
 	const agent = findAgent(session.agents, step.agent);
@@ -3747,13 +3753,16 @@ async function launchStep(
 			return;
 		}
 
-		// Honor `name=` when the caller asked for one; otherwise let `launch()`
-		// allocate from the supervisor-local registry (scout-N). The index must
-		// not race separate subagent tool calls for auto names.
+		// Honor `name=` in this order: a per-item `tasks[]` handle wins over the
+		// call-level `name=` (which applies to a single-step launch), and when
+		// neither is given `launch()` allocates from the supervisor-local registry
+		// (scout-N). The index must not race separate subagent tool calls for auto
+		// names.
+		const name = step.name ?? session.launchName;
 		const handle = await session.orchestrator.launch({
 			agent: launchedAgent,
 			task: step.task,
-			...(session.launchName ? { name: session.launchName } : {}),
+			...(name ? { name } : {}),
 			...(session.teamOverride ? { team: session.teamOverride } : {}),
 			...(resolved.model ? { model: resolved.model } : {}),
 			// Pin the provider (#123): a bare id like `workbuddy/...` may also
@@ -4010,6 +4019,7 @@ type Plan =
 			steps: Array<{
 				agent: string;
 				task: string;
+				name?: string;
 				model?: string;
 				preset?: string;
 				worktree?: boolean;
@@ -4042,6 +4052,16 @@ function buildUtilityPlan(params: VexillatioParams): UtilityPlan {
 			message: `tasks[] step ${unsupportedVerify + 1} cannot include \`verify\`; vexillatio does not run verification commands.`,
 		};
 	}
+	// `name` is a `subagent` concept: vexillatio allocates one handle per step
+	// itself (`<role>-N`, continuing the parent's existing children), so a
+	// per-item handle cannot be honored — refuse it instead of silently dropping.
+	const unsupportedName = steps.findIndex((item) => item.name !== undefined);
+	if (unsupportedName >= 0) {
+		return {
+			ok: false,
+			message: `tasks[] step ${unsupportedName + 1} cannot include \`name\`; vexillatio allocates one handle per step itself.`,
+		};
+	}
 	const invalid = steps.findIndex((item) => !item.agent.trim() || !item.task.trim());
 	if (invalid >= 0) {
 		return { ok: false, message: `tasks[] step ${invalid + 1} must include non-blank \`agent\` and \`task\`.` };
@@ -4485,10 +4505,12 @@ export function resolveExplicitLaunchName(
 export function buildPlan(params: {
 	agent?: string;
 	task?: string;
+	name?: string;
 	preset?: string;
 	tasks?: Array<{
 		agent: string;
 		task: string;
+		name?: string;
 		model?: string;
 		preset?: string;
 		worktree?: boolean;
@@ -4534,19 +4556,85 @@ export function buildPlan(params: {
 	const tasks = params.tasks as PlanStep[];
 	const problem = firstInvalidStep(tasks, "tasks[]");
 	if (problem) return { ok: false, message: problem };
-	return { ok: true, task: `${tasks.length} parallel tasks`, steps: tasks };
+	// A per-item `name` is a handle the caller will later steer/collect by, so a
+	// name that cannot be honored is refused for the WHOLE batch (see
+	// `resolveStepNames`) before any child is allocated.
+	const named = resolveStepNames(tasks, "tasks[]", params.name);
+	if (!named.ok) return { ok: false, message: named.message };
+	return { ok: true, task: `${tasks.length} parallel tasks`, steps: named.steps };
 }
 
 /** One entry of `tasks[]`. */
 interface PlanStep {
 	agent: string;
 	task: string;
+	name?: string;
 	model?: string;
 	preset?: string;
 	worktree?: boolean;
 	verify?: string[];
 }
 
+/**
+ * Resolve the per-item `name` handles of one `tasks[]` batch.
+ *
+ * Whole-batch rejection on purpose: a half-named batch would launch some
+ * children under the caller's handles and the rest under auto `role-N`, so the
+ * caller could neither predict nor control which child it later steers by name.
+ * Nothing is allocated yet (this runs before every launch), so refusing the
+ * batch costs nothing — unlike a partial start, which cannot be un-spawned.
+ *
+ * Returns a NEW array carrying the normalized handles; the caller's array is
+ * never rewritten, and an entry without a name keeps no `name` key at all.
+ */
+function resolveStepNames(
+	steps: PlanStep[],
+	label: string,
+	topLevelName: string | undefined,
+): { ok: true; steps: PlanStep[] } | { ok: false; message: string } {
+	const firstByName = new Map<string, number>();
+	const resolved: PlanStep[] = [];
+	for (let i = 0; i < steps.length; i += 1) {
+		const step = steps[i] ?? ({} as PlanStep);
+		if (step.name === undefined) {
+			resolved.push(step);
+			continue;
+		}
+		// Reuse the single-launch gate so trim/lowercase normalization and the
+		// grammar refusal can never drift between `name=` and `tasks[].name`.
+		const gate = resolveExplicitLaunchName(step.name, 1);
+		if (!gate.ok) {
+			return { ok: false, message: `${label}: step ${i + 1}: ${gate.message}` };
+		}
+		const name = gate.name as string;
+		const first = firstByName.get(name);
+		if (first !== undefined) {
+			return {
+				ok: false,
+				message: `${label}: steps ${first + 1} and ${i + 1} both ask for the name "${name}"; each child needs its own handle.`,
+			};
+		}
+		firstByName.set(name, i);
+		resolved.push({ ...step, name });
+	}
+	// A one-entry batch can name the child in both places. Agreement passes; a
+	// disagreement is refused rather than letting one silently win, because the
+	// child would then answer to a handle the caller did not mean to use.
+	const only = resolved[0];
+	if (resolved.length === 1 && only?.name !== undefined && topLevelName !== undefined) {
+		const top = resolveExplicitLaunchName(topLevelName, 1);
+		// An invalid top-level name keeps its own existing refusal (`name=` is
+		// validated by the launch handler); only a valid, differing name conflicts.
+		if (top.ok && top.name !== undefined && top.name !== only.name) {
+			return {
+				ok: false,
+				message: `${label}: step 1 asks for the name "${only.name}", but the call also passes name="${topLevelName.trim()}"; pass one.`,
+			};
+		}
+	}
+	return { ok: true, steps: resolved };
+}
+
 /**
  * True when a value is a non-blank string.
  * `Boolean("   ")` is true, so a whitespace-only task would otherwise pass and
@@ -5042,7 +5130,7 @@ export const WAIT_PARENT_DECISIONS = [
 export type WaitParentDecision = (typeof WAIT_PARENT_DECISIONS)[number];
 
 export const WAIT_TIMEOUT_HINT =
-	"wait does not stop children; choose stop/force_stop or extend/steer";
+	"wait only stopped waiting: the children are still running and keep their context. Prefer status/extend/steer_again; stop/force_stop retire them and discard that context, so use them only to abandon the work.";
 
 export interface WaitStillRunningChild {
 	name: string;
@@ -5160,10 +5248,93 @@ export interface StopRetireScope {
 	runId?: string | undefined;
 }
 
+/** What a child had already done by the time `stop` reached it. */
+interface StopSettled {
+	status?: ExecutionStatus;
+	/** ISO settle time, when the runtime observed one. */
+	at?: string;
+}
+
 /** One node `stop` will retire, with the run that owns it (#312). */
 interface StopTarget {
 	name: string;
 	runId: string;
+	/**
+	 * Set when the child had already finished: retiring it only reaps it, and the
+	 * reply has to say so instead of claiming an interruption.
+	 */
+	settled?: StopSettled;
+}
+
+/** The targets a named `stop` resolved, plus why it resolved none. */
+interface StopResolution {
+	targets: StopTarget[];
+	/** Present when the name matched a record that is already retired. */
+	note?: string;
+}
+
+/**
+ * A child that already finished is reaped, not stopped.
+ *
+ * `awaiting` means the runtime already collected a terminal snapshot; `exited`
+ * means its process is gone. A record whose execution is still `running` is NOT
+ * settled, even when a lifecycle state raced ahead of the process.
+ */
+function settledFromRecord(child: ChildRecord): StopSettled | undefined {
+	if (child.state !== "awaiting" && child.state !== "exited") return undefined;
+	const status = child.execution?.status;
+	if (status === "running") return undefined;
+	return status ? { status } : {};
+}
+
+/** The runtime job knows WHEN it settled; the outcome lives on the record, not on it. */
+function settledFromJob(job: { state: string; settledAt?: number }): StopSettled | undefined {
+	if (job.state !== "awaiting") return undefined;
+	return job.settledAt ? { at: new Date(job.settledAt).toISOString() } : {};
+}
+
+/**
+ * Resolve ONE named target from a persisted record.
+ *
+ * A `retired` record yields no target plus a note carrying its outcome and retire
+ * time — otherwise the caller learns only "nothing to stop", which is exactly how
+ * a child that finished a second earlier reads as a failed stop.
+ */
+function stopResolutionFromRecord(child: ChildRecord, runId: string): StopResolution {
+	if (child.state === "retired") {
+		return { targets: [], note: retiredRecordNote(child) };
+	}
+	const settled = settledFromRecord(child);
+	return { targets: [{ name: child.name, runId, ...(settled ? { settled } : {}) }] };
+}
+
+/** Same, for a live job the session tracks (the job table never holds `retired` in production). */
+function stopResolutionFromJob(job: {
+	name: string;
+	runId: string;
+	state: string;
+	settledAt?: number;
+}): StopResolution {
+	if (job.state === "retired") return { targets: [], note: `${job.name} is already retired.` };
+	const settled = settledFromJob(job);
+	return { targets: [{ name: job.name, runId: job.runId, ...(settled ? { settled } : {}) }] };
+}
+
+/** `worker-2 is already retired (execution: success, retired at 2026-…).` */
+function retiredRecordNote(child: ChildRecord): string {
+	const bits: string[] = [];
+	const status = child.execution?.status;
+	if (status) bits.push(`execution: ${status}`);
+	if (child.retiredAt) bits.push(`retired at ${child.retiredAt}`);
+	return `${child.name} is already retired${bits.length > 0 ? ` (${bits.join(", ")})` : ""}.`;
+}
+
+/** ` (execution: success, settled at 2026-…)`, or "" when nothing is known. */
+function stopSettledNote(settled: StopSettled | undefined): string {
+	const bits: string[] = [];
+	if (settled?.status) bits.push(`execution: ${settled.status}`);
+	if (settled?.at) bits.push(`settled at ${settled.at}`);
+	return bits.length > 0 ? ` (${bits.join(", ")})` : "";
 }
 
 /**
@@ -5258,8 +5429,13 @@ export async function stopAction(input: {
 	const jobs = runtime.activeJobs();
 	const active = jobs.filter((job) => job.state !== "retired");
 	let targets: StopTarget[];
+	/** Describes the already-retired record a NAMED stop resolved to no target. */
+	let alreadyRetired: string | undefined;
 	if (params.all) {
-		targets = active.map((job) => ({ name: job.name, runId: job.runId }));
+		targets = active.map((job) => {
+			const settled = settledFromJob(job);
+			return { name: job.name, runId: job.runId, ...(settled ? { settled } : {}) };
+		});
 	} else {
 		// Local const so the earlier `name`/`all` guard narrows through the lookup.
 		const name = params.name;
@@ -5311,33 +5487,48 @@ export async function stopAction(input: {
 					if (!permissive) {
 						return fail(`unknown child: ${params.name} (not tracked by this session).`, ErrorCodes.NOT_FOUND);
 					}
-					targets = permissive.child.state === "retired" ? [] : [{ name: permissive.child.name, runId: permissive.runId }];
+					const resolved = stopResolutionFromRecord(permissive.child, permissive.runId);
+					targets = resolved.targets;
+					alreadyRetired = resolved.note;
 				} else {
 					return fail(`unknown child: ${params.name} (not tracked by this session).`, ErrorCodes.NOT_FOUND);
 				}
 			} else {
-				targets = found.child.state === "retired" ? [] : [{ name: found.child.name, runId: found.runId }];
+				const resolved = stopResolutionFromRecord(found.child, found.runId);
+				targets = resolved.targets;
+				alreadyRetired = resolved.note;
 			}
 		} else {
-			targets = target.state === "retired" ? [] : [{ name: target.name, runId: target.runId }];
+			const resolved = stopResolutionFromJob(target);
+			targets = resolved.targets;
+			alreadyRetired = resolved.note;
 		}
 	}
-	if (targets.length === 0) return ok("No non-retired children to stop.");
+	if (targets.length === 0) {
+		return ok(
+			alreadyRetired ? `No non-retired children to stop. ${alreadyRetired}` : "No non-retired children to stop.",
+		);
+	}
 
 	// Stop every watcher before any retire starts: a later target must not finish
 	// its own watch (and notify/release) while an earlier target is being retired.
 	for (const { name } of targets) runtime.cancelWatch(name);
 
 	const stopped: string[] = [];
+	const reaped: string[] = [];
 	const failures: string[] = [];
-	for (const { name, runId } of targets) {
+	for (const target of targets) {
+		const { name, runId } = target;
 		try {
 			// The runtime job may have been released after the target snapshot was
 			// taken. `scope` hands the resolve-time run to the executor, which reads
 			// THAT record rather than picking one across runs (#312).
 			await retire(name, retireOpts, { runId });
 			runtime.release(name);
-			stopped.push(name);
+			// A child that had already finished is reaped, not stopped: "Stopped 1
+			// child" for a success claims an interruption that never happened.
+			if (target.settled) reaped.push(`${name}${stopSettledNote(target.settled)}`);
+			else stopped.push(name);
 		} catch (error) {
 			// If the retire chain fails, restore the completion watcher so a
 			// still-live child is not orphaned by the explicit stop attempt.
@@ -5346,9 +5537,16 @@ export async function stopAction(input: {
 		}
 	}
 	const mode = force ? "force-stopped" : "Stopped";
-	const summary = stopped.length
-		? `${mode} ${stopped.length} child${stopped.length === 1 ? "" : "ren"}: ${stopped.join(", ")}.`
-		: "No children were stopped.";
+	const lines: string[] = [];
+	if (stopped.length > 0) {
+		lines.push(`${mode} ${stopped.length} child${stopped.length === 1 ? "" : "ren"}: ${stopped.join(", ")}.`);
+	}
+	if (reaped.length > 0) {
+		lines.push(
+			`Retired ${reaped.length} already-settled child${reaped.length === 1 ? "" : "ren"}: ${reaped.join(", ")}.`,
+		);
+	}
+	const summary = lines.length > 0 ? lines.join("\n") : "No children were stopped.";
 	return failures.length
 		? fail(`${summary}\nFailed to stop: ${failures.join("; ")}`, ErrorCodes.RETIRE_FAILED)
 		: ok(summary);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-legion",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "description": "Pi Legion v2: recursive centurion teams on Pi. Children run in-process by default (rpc only for a worktree-owning centurion); shared SQLite WAL legion.db. Declarative per-team phase machine (built-in default: planning/implementing/reviewing/verifying), parent/child/sibling legion_mail, three-layer /legion UI, upward MR trees, squad resume.",
   "type": "module",
   "license": "MIT",

package/src/extension/notify.ts

@@ -72,7 +72,14 @@ export interface RenewalProposal {
 export interface CompletionInput {
 	name: string;
 	agent?: string;
-	execution: { status: string; reason?: string };
+	execution: {
+		status: string;
+		reason?: string;
+		/** Provider transcript detail; shown only when `reason` cannot carry it. */
+		stopReason?: string | null;
+		errorMessage?: string | null;
+		errorKind?: string;
+	};
 	output: string;
 	/** Full output on disk; the truncated preview names this path. */
 	outputFile?: string;
@@ -106,13 +113,31 @@ export interface CompletionDetails {
 	status: CompletionStatus;
 	name: string;
 	agent?: string;
-	execution: { status: string; reason?: string };
+	execution: {
+		status: string;
+		reason?: string;
+		stopReason?: string | null;
+		errorMessage?: string | null;
+		errorKind?: string;
+	};
 	acceptance?: { status: string; level?: string };
 	sessionFile?: string;
 	outputBytes: number;
 	recycled?: boolean;
 }
 
+/**
+ * Provider text the synthetic `reason` cannot carry (`unknown stopReason: …`).
+ *
+ * Display-only and bounded: an HTTP error body can be a whole HTML page, and a
+ * notice is a summary. Absent when the message is already the reason.
+ */
+function errorDetailFor(execution: { reason?: string; errorMessage?: string | null }): string | undefined {
+	const message = execution.errorMessage?.trim();
+	if (!message || message === execution.reason?.trim()) return undefined;
+	return `error: ${message.length > 400 ? `${message.slice(0, 400)}…` : message}`;
+}
+
 /** `1234` -> `1.2 KB`, so the collapsed line says how much landed. */
 export function formatSize(bytes: number): string {
 	if (bytes < 1024) return `${bytes} B`;
@@ -318,6 +343,7 @@ export function formatCompletionNotice(input: CompletionInput): CompletionNotice
 		`Background task ${status}: **${label}**`,
 		"",
 		`execution: ${input.execution.status}${reason}`,
+		errorDetailFor(input.execution),
 		acceptance,
 		"",
 		preview,
@@ -344,6 +370,9 @@ export function formatCompletionNotice(input: CompletionInput): CompletionNotice
 			execution: {
 				status: input.execution.status,
 				reason: input.execution.reason,
+				...(input.execution.stopReason !== undefined ? { stopReason: input.execution.stopReason } : {}),
+				...(input.execution.errorMessage !== undefined ? { errorMessage: input.execution.errorMessage } : {}),
+				...(input.execution.errorKind !== undefined ? { errorKind: input.execution.errorKind } : {}),
 			},
 			acceptance: input.acceptance
 				? {

package/src/extension/playbook.ts

@@ -8,10 +8,10 @@ export const PARENT_PLAYBOOK = [
 	"Pi Legion playbook (frozen — do not invent a launch recipe):",
 	"1. Call the `subagent` tool immediately with the matching role from the roster in this prompt. Do not substitute bash/curl/web fetch for a search or research role.",
 	'   One child:  subagent({ agent: "<role>", task: "...", name?: "scout-a" })  // optional name= registers that handle (not auto scout-N)',
-	"   Parallel:   subagent({ tasks: [{ agent, task }, { agent, task }] })",
+	"   Parallel:   subagent({ tasks: [{ agent, task, name?: \"scout-a\" }, { agent, task }] })  // a per-item name= is that child's handle; every handle in one batch must differ",
 	"2. Prefer tasks[] for independent parallel work. Children are in-process by default; a separate `pi` process is used only when the launch needs a worktree — and since only a centurion may hold one, that is the only launch that goes over rpc. No pane or tab is created.",
 	"3. Then return control. A completion message wakes this session when idle; if it is still working, the notice waits until the current turn ends. Use `wait` with `name` or `all: true` when you need blocking results, and `collect` to inspect a child's session JSONL. Esc / wait interrupt only ends the parent turn's wait — children keep running and settle still notifies; only an explicit `stop` or session exit retires them. A wait interrupted by Esc returns `interrupted (parent turn ended; children still running)`. In `pi --print` or JSON mode, session shutdown waits for live async children to settle (up to each child's turn timeout) before retiring them. Use same-turn `wait`/`collect` or `async: false` when that print turn must include the child's result.",
-	"4. Later control is only through `subagent({ action, name?, message? })`; `status` with no name (or `all: true`) overviews live children, with `name` for one child; use `stop` to gracefully retire one child or all tracked children (`force: true` for hard retire when soft stop is insufficient). A `wait` timeout does not stop children — the result lists decisions (`extend` / `steer_again` / `stop` / `force_stop`) for the parent to choose. If a child exits oddly (Model not found, missing tools, memory refused, …), call `subagent({ action: \"diagnose\" })` or ask the user to run `/legion doctor` / `/legion doctor models` — children run without host extensions unless the role inherits them, so a provider package the child needs must be passed explicitly. Do not tell a child to message or prompt the parent directly.",
+	"4. Later control is only through `subagent({ action, name?, message? })`; `status` with no name (or `all: true`) overviews live children, with `name` for one child; use `stop` to gracefully retire one child or all tracked children (`force: true` for hard retire when soft stop is insufficient). A `wait` timeout does not stop children — the result lists decisions (`extend` / `steer_again` / `stop` / `force_stop`) for the parent to choose. A `stop` that reaches a child which already finished answers `Retired … already-settled` (or `… is already retired`) — nothing was interrupted, so that is not a failed stop. If a child exits oddly (Model not found, missing tools, memory refused, …), call `subagent({ action: \"diagnose\" })` or ask the user to run `/legion doctor` / `/legion doctor models` — children run without host extensions unless the role inherits them, so a provider package the child needs must be passed explicitly. Do not tell a child to message or prompt the parent directly.",
 	"5. A collect timeout with a live child is a progress signal, not a verdict. Check status or session JSONL before deciding to steer or resume.",
 	"6. Isolation belongs to centurion: each centurion owns one worktree, and members stay `worktree: false` in-process. Passing `worktree: true` on a non-centurion warns once and is forced false.",
 	"7. Launch with `verify: [\"npm run typecheck\", \"npm test\"]` when the project has a mechanical verifier. The extension runs those commands itself in the child worktree at collect time; the child does not need to paste test output.",

package/src/extension/runtime.ts

@@ -60,7 +60,18 @@ import type { TreeNodeSnapshot } from "../tui/tree-view.ts";
 import type { PhaseMachine } from "../legion/phase-machine.ts";
 
 export interface CollectSnapshot {
-	execution: { status: string; reason?: string };
+	execution: {
+		status: string;
+		reason?: string;
+		/**
+		 * Failure detail carried to the parent notice. `reason` is often a synthetic
+		 * sentence (`unknown stopReason: …`), so the provider text is kept beside it
+		 * instead of being lost between the transcript and the notice.
+		 */
+		stopReason?: string | null;
+		errorMessage?: string | null;
+		errorKind?: string;
+	};
 	output: string;
 	/** Full output persisted to disk; named in the notice so a truncated preview has a one-step recovery. */
 	outputFile?: string;

package/src/runs/orchestrator.ts

@@ -309,13 +309,15 @@ export const COLLECT_GRACE_EXTENSIONS = 2;
 /**
  * Shown when this collect() call's budget elapses and the child is still in-turn.
  *
- * The "cumulative since launch" wording below is legacy: `collect()` starts its
- * deadline from the moment it is called (`orchestrator.ts` `let deadline = ...`),
- * not from launch. The literal is user-visible and asserted in integration tests,
- * so D6 of `docs/contracts/vexillatio-nonblocking-launch-v1.md` deliberately left
- * it untouched; do not read it as the actual budget origin.
+ * The budget is per collect call, never cumulative since launch: the deadline is
+ * `now + timeoutMs` at the top of `collect()`. The old literal claimed otherwise
+ * and was frozen only because integration tests pinned the string; the wording is
+ * honest now.
+ *
+ * Elapsing here NEVER terminates the child: `classifyOutcome` reports `running`,
+ * `shouldRecycleAfterCollect` refuses to recycle it, and the watch re-arms.
  */
-export const COLLECT_DEADLINE_REASON = "collect deadline (cumulative since launch) exceeded; child still alive";
+export const COLLECT_DEADLINE_REASON = "collect deadline (per collect attempt) exceeded; child still alive";
 /** Shown when a live child's session ends on an OpenAI/GPT connection blip. */
 export const TRANSIENT_CONNECTION_REASON = "transient connection error; RPC child still alive";
 /**
@@ -2890,9 +2892,10 @@ export class Orchestrator {
 		if (execution.status !== "running") this.recordSettled(child, execution, isLastTurnComplete(parsed));
 		if (!isRetired()) this.onChildUpdate(child);
 		const output = execution.status !== "running" && parsed.lastTurnOutput === null ? "" : parsed.output;
-		if (isRetired()) {
-			return { execution, output, usage: parsed.usage, model: parsed.model ?? child.model ?? null, acceptance };
-		}
+		// A stop can land between the snapshot and here. The lifecycle state must not
+		// be revived (above), but the terminal text still belongs on disk: this collect
+		// is the only writer of the artifact, so returning early here dropped the
+		// child's last answer whenever an explicit stop won the race.
 		let outputFile: string | undefined;
 		if (execution.status === "running") child.outputFile = undefined;
 		else {