pi-legion 5.0.1 → 5.2.0

package/index.ts

@@ -11,6 +11,7 @@
  *   is still working. Running children are painted next to the input box.
  */
 
+import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentToolResult, AgentToolUpdateCallback } from "@earendil-works/pi-agent-core";
 import type {
@@ -23,9 +24,11 @@ import { RpcSupervisor } from "./src/supervisor/rpc-supervisor.ts";
 import { InProcessSupervisor } from "./src/supervisor/inprocess-supervisor.ts";
 import { runAtAbsoluteDepth } from "./src/supervisor/inprocess-depth.ts";
 import { notifyInProcessSlotReleased, RoutingSupervisor } from "./src/supervisor/routing-supervisor.ts";
-import type { LegionSupervisor } from "./src/supervisor/types.ts";
+import type { AbortOutcome, InFlightToolStack, LegionSupervisor, SteerDisposition } from "./src/supervisor/types.ts";
+import { inFlightToolStackOf } from "./src/supervisor/types.ts";
+import { withInFlightToolLine } from "./src/extension/legion-status.ts";
 import { InMemoryUIProxy, type UIProxy } from "./src/supervisor/ui-proxy.ts";
-import { discoverAgents, findAgent, formatAgentRoster, BUILTIN_AGENTS_DIR } from "./src/agents/agents.ts";
+import { discoverAgents, findAgent, formatAgentRoster, parsePhaseMachine, BUILTIN_AGENTS_DIR } from "./src/agents/agents.ts";
 import {
 	applyAgentOverrides,
 	applyDefaultModel,
@@ -42,21 +45,23 @@ import { providerForModel, type ProviderLookup } from "./src/runs/provider-pin.t
 import { resolveStepModel } from "./src/agents/step-model.ts";
 import { checkModelScope } from "./src/agents/model-scope.ts";
 import {
+	legionSettingsForRun,
 	loadSubagentSettings,
 	resolveSubagentSettings,
 } from "./src/agents/settings.ts";
 import { resolveTeamContext } from "./src/agents/context.ts";
-import { createSessionRuntime, renderLiveChildStatus, type SessionRuntime, shouldRecycleAfterCollect, type WaitResult } from "./src/extension/runtime.ts";
+import { createSessionRuntime, renderLiveChildStatus, type ClaimedCollect, type CollectSnapshot, type SessionRuntime, shouldRecycleAfterCollect, type WaitResult } from "./src/extension/runtime.ts";
 import { createDbEventSource, createLegionEventBus, type DbEventSource, type LegionEventBus } from "./src/extension/event-bus.ts";
 import { LegionPostman, registerLegionTools, type LegionMailCommand } from "./src/extension/legion-tools.ts";
-import type { PhaseMachine } from "./src/legion/phase-machine.ts";
-import { LEGION_DB_ENV, LEGION_NODE_ID_ENV } from "./src/runs/args.ts";
+import type { PhaseDefinition, PhaseMachine, PhaseTransitionRule } from "./src/legion/phase-machine.ts";
+import { LEGION_DB_ENV, LEGION_NODE_ID_ENV, LEGION_PHASES_ENV } from "./src/runs/args.ts";
 import type { VerifyRunner } from "./src/runs/acceptance.ts";
 import { legionDbPath, openLegionDb, type DatabaseSync } from "./src/legion/db.ts";
 import { appendEvent, maxEventId } from "./src/legion/events.ts";
 import { attachUsageTotals, upsertUsage } from "./src/legion/usage.ts";
-import { getChildByName, getChildren, getNode, getSubtree, insertNode, type LegionNode, updateNode } from "./src/legion/nodes.ts";
-import { DEFAULT_LEGION_SETTINGS, type LegionSettings } from "./src/shared/types.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 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 {
@@ -106,6 +111,24 @@ import {
 	type OrchestratorLegionContext,
 } from "./src/runs/orchestrator.ts";
 import { RunStore, pickChildByName } from "./src/runs/store.ts";
+import {
+	beginMailHold,
+	endMailHold,
+	pollInbox,
+	redeliverMail,
+	renderReleasedMail,
+	takePendingMail,
+	type MailReleaseSeam,
+} from "./src/legion/mail-release.ts";
+import type { LegionMessage } from "./src/legion/mail.ts";
+import {
+	describeChildScopeCandidates,
+	foundElsewhere,
+	foundInScope,
+	resolveScopedChild,
+	scopeHitFor,
+	type ChildScopeCandidate,
+} from "./src/runs/child-scope.ts";
 import {
 	candidateStoreRoots,
 	resolveChildAcrossStores,
@@ -113,6 +136,7 @@ import {
 	type CandidateStore,
 } from "./src/runs/store-lookup.ts";
 import { RUN_OWNER_FILE, ownerState } from "./src/runs/owner.ts";
+import { isStaleUiError } from "./src/tui/status.ts";
 import { measureProgress, readSessionLines } from "./src/runs/progress-signal.ts";
 import { resolveLaunchWorktree } from "./src/runs/worktree.ts";
 import {
@@ -127,6 +151,7 @@ import {
 	type Execution,
 	type ModelOrigin,
 	type RetireOptions,
+	type RunRecord,
 	type SpawnMode,
 	SubagentError,
 	type SubagentsSettings,
@@ -138,9 +163,96 @@ import {
 // Parameters
 // ---------------------------------------------------------------------------
 
+/**
+ * One transition of a declared phase machine (#371).
+ *
+ * Mirrors `PhaseTransitionRule` in `src/legion/phase-machine.ts`. The shape is
+ * declared here rather than accepting `Type.Any()` so the MODEL sees what a
+ * machine is made of; the authoritative validation still happens once, in
+ * `parsePhaseMachine`, at launch (`orchestrator.declaredPhaseMachine`).
+ */
+const PhaseRuleParams = Type.Object({
+	to: Type.String({ description: "Target phase id." }),
+	require: Type.Optional(
+		Type.Array(Type.String(), {
+			description: 'Conditions ANDed into this edge, e.g. ["contract_file","children_settled","verdict_ok","verification_passed"].',
+		}),
+	),
+	actorRole: Type.Optional(Type.String({ description: "When set, only this actor role may take the edge." })),
+	rework: Type.Optional(Type.Boolean({ description: "Counts as a rework step (increments rework_count, capped by maxRework)." })),
+	notifyParent: Type.Optional(Type.Boolean({ description: "Notify the parent when taken." })),
+});
+
+/** One phase of a declared machine (#371). */
+const PhaseParams = Type.Object({
+	id: Type.String({ description: "Phase id." }),
+	require: Type.Optional(
+		Type.Array(Type.String(), { description: "Conditions ANDed into every edge leaving this phase." }),
+	),
+	next: Type.Optional(Type.Array(PhaseRuleParams, { description: "Allowed exits. A phase with none must be `terminal`." })),
+	timeoutMs: Type.Optional(Type.Number({ description: "Advisory clock only; never kills work." })),
+	terminal: Type.Optional(Type.Boolean({ description: "Terminal phases may not transition out." })),
+});
+
+/** A whole machine, with its entry phase and rework cap (#371). */
+const PhaseMachineParams = Type.Object({
+	phases: Type.Array(PhaseParams),
+	start: Type.Optional(Type.String({ description: "Entry phase; defaults to the first declared phase." })),
+	maxRework: Type.Optional(Type.Integer({ minimum: 0 })),
+});
+
+/**
+ * #371 (m9): the schema above and the real machine types must not drift.
+ *
+ * `parsePhaseMachine` is the authority, but the model reads THIS schema: a field
+ * added to `PhaseDefinition` and forgotten here would be invisible to every
+ * caller, and a field offered here that the parser rejects would be advertised
+ * and then refused. Both are silent at runtime, so they are made loud at compile
+ * time.
+ *
+ * The comparison is against a LOOSENED copy of the real types, because the schema
+ * is deliberately wider in exactly two documented places: `require` arrives as
+ * raw strings (the validator resolves them into `PhaseCondition`s) and `next` may
+ * be omitted (a phase with no exits must be `terminal`, which the validator
+ * checks). `injected` is excluded for the same reason — it is the normalizer's
+ * marker, never the caller's.
+ */
+type PhaseRuleSchema = Static<typeof PhaseRuleParams>;
+type PhaseSchema = Static<typeof PhaseParams>;
+type PhaseMachineSchema = Static<typeof PhaseMachineParams>;
+type CallerRule = Omit<PhaseTransitionRule, "injected" | "require"> & { require?: string[] };
+type CallerPhase = Omit<PhaseDefinition, "next" | "require" | "injected"> & { next?: CallerRule[]; require?: string[] };
+type CallerMachine = Omit<PhaseMachine, "phases"> & { phases: CallerPhase[] };
+/**
+ * Mutual assignability plus an exact KEY SET. Assignability alone would miss a
+ * property added as optional on one side (extra optional properties are legal to
+ * assign), which is precisely how a schema silently stops describing a field the
+ * parser requires.
+ */
+type SameShape<A, B> = [A] extends [B]
+	? [B] extends [A]
+		? [keyof A] extends [keyof B]
+			? [keyof B] extends [keyof A] ? true : never
+			: never
+		: never
+	: never;
+const phaseRuleSchemaParity: SameShape<CallerRule, PhaseRuleSchema> = true;
+const phaseSchemaParity: SameShape<CallerPhase, PhaseSchema> = true;
+const phaseMachineSchemaParity: SameShape<CallerMachine, PhaseMachineSchema> = true;
+// Referenced so `noUnusedLocals` cannot quietly delete the assertions above.
+void phaseRuleSchemaParity;
+void phaseSchemaParity;
+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:
@@ -154,7 +266,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. Reserved for `centurion` (#214): any other role asking for true is downgraded to false with a one-time warning.",
+				"Parent decides isolation for this child. true = own git branch, child delivers that branch (an MR when the repository has a remote). 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(
@@ -172,6 +284,7 @@ const SubagentParams = Type.Object({
 				Type.Literal("launch"),
 				Type.Literal("continue"),
 				Type.Literal("steer"),
+				Type.Literal("abort"),
 				Type.Literal("resume"),
 				Type.Literal("retire"),
 				Type.Literal("status"),
@@ -181,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(
@@ -211,7 +324,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. 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.",
+				"Parent decides isolation. true = isolated git branch, child delivers that branch (an MR when the repository has a remote). 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(
@@ -220,6 +333,35 @@ const SubagentParams = Type.Object({
 			"Verification commands the extension runs itself in the child worktree at collect time (launch only). Each must exit 0; the first non-zero exit rejects the child's verdict as `rejected (verified-path)`. The worker does not need to paste test output.",
 		}),
 	),
+	phases: Type.Optional(
+		Type.Union(
+			[
+				Type.Array(PhaseParams, {
+					description:
+						"A phase list, in pipeline order. The team is born in `start` (or the first entry).",
+				}),
+				PhaseMachineParams,
+				Type.String({
+					description:
+						'One-line JSON for the same machine, or an indented list of "  - id: <name>" entries.',
+				}),
+			],
+			{
+				description:
+					"ROOT-ONLY, centurion-only, launch-only (#371). The team's state machine, declared by the root at dispatch time. " +
+					"Where a machine is declared the team walks it exactly as it did before; where none is, the centurion gets no phase, no `legion_phase` and no collection prompt — it just does the work and returns a verdict. " +
+					"So declare this only for a real multi-agent delivery; a one-file change belongs to a worker. " +
+					"A machine must be able to REACH a terminal phase (`done`/`failed`/`aborted`) or it is refused before anything is created. " +
+					'Example — solo, no children required: `phases:[{id:"planning"},{id:"implementing",next:[{to:"done"}]},{id:"done",terminal:true}]`.',
+			},
+		),
+	),
+	start: Type.Optional(
+		Type.String({
+			description:
+				"Entry phase for a `phases` LIST (a machine object or JSON string carries its own `start`, which wins). Only meaningful with `phases`.",
+		}),
+	),
 	agentScope: Type.Optional(
 		Type.Union(
 			[Type.Literal("user"), Type.Literal("project"), Type.Literal("both")],
@@ -239,6 +381,12 @@ const SubagentParams = Type.Object({
 			description: "wait: REQUIRED unless name is set — wait for every live (working/blocked) child; mutually exclusive with name. stop: stop every non-retired child; status: overview of all live (non-retired) children under cwd",
 		}),
 	),
+	runId: Type.Optional(
+		Type.String({
+			description:
+				'control actions (status/collect/stop/continue/resume/steer/abort/retire): name the run that holds the child, instead of the run this session owns. A name is resolved against this session\'s direct children first; a same-named node in another run is reported (as `not a direct child` or as an ambiguity), never silently adopted. Example: subagent({ action: "collect", name: "worker-0", runId: "r-4fd626ee" }).',
+		}),
+	),
 	timeoutMs: Type.Optional(
 		Type.Number({
 			description: "wait: per-child timeout in ms; event-driven completion returns early (default: role turnTimeoutMs)",
@@ -250,6 +398,12 @@ const SubagentParams = Type.Object({
 			'stop only: when true, hard-retire via SIGTERM→SIGKILL + descendant sweep (retire hardening). Omit/false = graceful retire. Example: subagent({ action: "stop", name: "worker-0", force: true }).',
 		}),
 	),
+	clearQueued: Type.Optional(
+		Type.Boolean({
+			description:
+				'abort only: clear the child\'s queued steering/follow-up messages before interrupting it (default true). Omit for true. Example: subagent({ action: "abort", name: "worker-0" }).',
+		}),
+	),
 	message: Type.Optional(
 		Type.String({ description: "Text for steer/continue" }),
 	),
@@ -330,10 +484,22 @@ interface LegionRuntimeIdentity {
 	dbEventSource: DbEventSource;
 	postman: LegionPostman;
 	childNodeId(name: string): string | undefined;
+	/**
+	 * #351: the phase machine a node's role card declares, by role. Carried on the
+	 * identity (i.e. recorded when the tree is built) so every orchestrator this
+	 * process constructs can resolve a custom phase name for a parent retire.
+	 */
+	machineForRole?: (role: string | null | undefined) => PhaseMachine | undefined;
 }
 
+/**
+ * #358 review (major 1): the defaults are filled, but the explicitness of every
+ * value travels with them — see `legionSettingsForRun`. A plain spread here tagged
+ * the built-in `phaseTimeouts` as operator decisions, and a card's `timeoutMs` on
+ * `planning`/`implementing`/… was silently ignored.
+ */
 function settingsForLegion(settings: ReturnType<typeof loadSubagentSettings>): LegionSettings {
-	return { ...DEFAULT_LEGION_SETTINGS, ...(settings.legion ?? {}), phaseTimeouts: { ...DEFAULT_LEGION_SETTINGS.phaseTimeouts, ...(settings.legion?.phaseTimeouts ?? {}) } };
+	return legionSettingsForRun(settings);
 }
 
 function runStoreFor(cwd: string, dbPathOverride?: string): RunStore {
@@ -513,6 +679,157 @@ function phaseMachineForRole(role: string | null | undefined, cwd: string, setti
 	}
 }
 
+/**
+ * The phase machine for THIS node, declaration first (#371 contract §2).
+ *
+ * Resolution order, exactly as the contract freezes it:
+ *
+ *   1. the machine the root declared in this dispatch (`PI_LEGION_PHASES`)
+ *   2. the role card's `phases:`
+ *   3. neither — and then the node has NO machine, which is a different answer
+ *      from "use the built-in one": no phase, no `legion_phase`, no collection
+ *      prompt (invariant I2).
+ *
+ * Gated on the role because the environment is inherited: an in-process member
+ * literally shares its lead's `process.env`, and a worker must never adopt its
+ * lead's team machine as its own. A nested centurion cannot exist (G1), so the
+ * gate loses nothing.
+ *
+ * A pre-existing ledger row with a phase but no obtainable declaration keeps the
+ * card path and, failing that, no machine — the same degrade-don't-throw rule the
+ * card lookup above follows. The row's phase is still enough for `legion_phase`
+ * to stay registered (see `registerLegionTools`), so an in-flight team is never
+ * stranded by an upgrade.
+ */
+function phaseMachineForNode(role: string | null | undefined, cwd: string, settings: SubagentsSettings): PhaseMachine | undefined {
+	if (role === "centurion") {
+		const declared = process.env[LEGION_PHASES_ENV];
+		if (declared) {
+			try {
+				const machine = parsePhaseMachine(declared, LEGION_PHASES_ENV);
+				if (machine) return machine;
+			} catch (error) {
+				console.warn(`[pi-legion] ignoring an unreadable ${LEGION_PHASES_ENV} declaration: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		}
+	}
+	return phaseMachineForRole(role, cwd, settings);
+}
+
+/**
+ * #372 B: the machine a team declared INLINE at dispatch, as it was PERSISTED.
+ *
+ * `phaseMachineForRole` above answers "what does this role's card declare", and
+ * `phaseMachineForNode` answers it for a child process through the inherited
+ * `PI_LEGION_PHASES` environment. Neither can answer it for the `/legion` tree:
+ * the tree renders OTHER nodes, and since #371 the machine can be declared per
+ * DISPATCH (`subagent({ phases })`, contract §2) with no card involved — so the
+ * most explicitly configured teams were exactly the ones the panel could not
+ * describe.
+ *
+ * The durable record of that declaration is the child record the launch wrote
+ * (`ChildRecord.phases`, contract `legion-session-continuity-v1` §4), which is
+ * why this reads run.json rather than this process's `Orchestrator` snapshot:
+ * the snapshot dies with the launch call, while the panel must still answer after
+ * a reload, in a later process, and in a reopened session.
+ *
+ * The record lives in the run of the process that DISPATCHED the node, not in the
+ * node's own run, so this cannot read `store.readRun(node.runId)` — it is given
+ * the dispatch run when the caller knows it (`dispatchRunId`) and searches the
+ * registry only as a fallback.
+ *
+ * #372 M1: a bare node id is NOT an identity. Every run in a checkout contains a
+ * `root.team`, and `listRuns()` is oldest-first, so "the first run whose children
+ * mention this id" picked the OLDEST run — an old team's declaration would paint
+ * today's node, and a team that declared nothing today would inherit a machine
+ * from a run that ended long ago. Two rules follow, and both are load-bearing:
+ *
+ *   1. with `dispatchRunId`, ONLY that run answers (and "no record with `phases`"
+ *      there means "declared nothing", not "look elsewhere");
+ *   2. without it, the registry answer is used only when exactly ONE run owns the
+ *      id — ambiguity is a MISS, never a guess (the same convention
+ *      `storedNodeForJob` uses for identities it cannot disambiguate).
+ *
+ * Only the team that declared the machine has a record; a worker never does, and
+ * nothing is inferred for it here (it inherits from its lead while rendering,
+ * #298).
+ */
+export function inlinePhaseMachineForNode(
+	nodeId: string,
+	runs: readonly Pick<RunRecord, "runId" | "children">[],
+	dispatchRunId?: string | null,
+): PhaseMachine | undefined {
+	if (dispatchRunId) {
+		const dispatchRun = runs.find((run) => run.runId === dispatchRunId);
+		return dispatchRun?.children.find((child) => child.nodeId === nodeId)?.phases;
+	}
+	const owners = runs.filter((run) => run.children.some((child) => child.nodeId === nodeId));
+	if (owners.length !== 1) return undefined;
+	const [owner] = owners;
+	return owner?.children.find((child) => child.nodeId === nodeId)?.phases;
+}
+
+/**
+ * #372 B/M1/m4: the `/legion` tree's inline-declaration lookup.
+ *
+ * A factory rather than an inline closure so the plumbing is testable without
+ * booting the extension: the run lookup, the clock and the cwd are all injected.
+ * The review found the previous closure had NO test coverage at all — dropping the
+ * `parentRunId` argument or keying the cache by `node.id` alone kept every test
+ * green while the panel leaked another run's declaration.
+ *
+ * Three properties, each load-bearing:
+ *
+ *  - **run-scoped cache keys** `(parentRunId, node.id)`. `node.id` repeats in
+ *    every run of a checkout (`root.team`), so an id-only key serves one run's
+ *    answer for another run's node — and, once cached, for the rest of the
+ *    process (#372 M1).
+ *  - **misses are cached, briefly.** A miss is a real answer ("this team declared
+ *    nothing") and without caching it every repaint paid a runs-registry read per
+ *    undeclared team (#372 m4). `MISS_TTL_MS` bounds both that cost and the one
+ *    race the cache can lose: the node row exists a moment before `persistChild`
+ *    writes the record, and the TTL is the same 1s the store itself uses for a
+ *    foreign in-place `run.json` rewrite, so a miss observed in that window heals
+ *    by itself instead of freezing until restart.
+ *  - **the dispatching run is passed through** to `inlinePhaseMachineForNode`,
+ *    which is the only thing that can pick the right record (#372 M1).
+ */
+export function createInlineMachineLookup(input: {
+	/** This process's cwd, read at call time (it changes with the session). */
+	cwd: () => string | undefined;
+	/** The store for a checkout — injected so a test can count registry reads. */
+	runStoreFor: (cwd: string) => Pick<RunStore, "listRuns">;
+	now?: () => number;
+}): (node: { id: string; role: string | null; parentRunId: string | null }) => PhaseMachine | undefined {
+	const positives = new Map<string, PhaseMachine>();
+	const misses = new Map<string, number>();
+	const now = input.now ?? Date.now;
+	const MISS_TTL_MS = 1_000;
+	return (node) => {
+		const key = `${node.parentRunId ?? "-"}\u0000${node.id}`;
+		const hit = positives.get(key);
+		if (hit) return hit;
+		const nowMs = now();
+		const missUntil = misses.get(key);
+		if (missUntil !== undefined && nowMs < missUntil) return undefined;
+		const cwd = input.cwd();
+		if (!cwd) return undefined;
+		let machine: PhaseMachine | undefined;
+		try {
+			machine = inlinePhaseMachineForNode(node.id, input.runStoreFor(cwd).listRuns(), node.parentRunId);
+		} catch {
+			// The panel must never break on an unreadable runs directory; the role
+			// lookup still runs, so a card-declared team keeps rendering.
+			machine = undefined;
+		}
+		if (machine) {
+			positives.set(key, machine);
+			misses.delete(key);
+		} else misses.set(key, nowMs + MISS_TTL_MS);
+		return machine;
+	};
+}
+
 function createLegionRuntime(input: {
 	pi: ExtensionAPI;
 	supervisor: LegionSupervisor;
@@ -528,6 +845,8 @@ function createLegionRuntime(input: {
 	registerTools: boolean;
 	/** #298: the team root's declared phase machine, when its card supplies one. */
 	machine?: PhaseMachine;
+	/** #351: by-role resolver for the abort path (see LegionRuntimeIdentity). */
+	machineForRole?: (role: string | null | undefined) => PhaseMachine | undefined;
 }): LegionRuntimeIdentity {
 	const self = getNode(input.db, input.nodeId);
 	const eventBus = input.eventBus;
@@ -545,6 +864,7 @@ function createLegionRuntime(input: {
 			pi: input.pi, supervisor: input.supervisor, db: input.db, dbPath: input.dbPath,
 			eventBus, settings: input.settings, cwd: input.cwd, storeRootDir: input.storeRootDir,
 			parentNodeId: input.nodeId, node, message: mail.text,
+			...(input.machineForRole ? { machineForRole: input.machineForRole } : {}),
 		}),
 	});
 	const identity: LegionRuntimeIdentity = {
@@ -564,6 +884,7 @@ function createLegionRuntime(input: {
 		dbEventSource,
 		postman,
 		childNodeId: (name) => getChildByName(input.db, input.nodeId, name)?.id,
+		...(input.machineForRole ? { machineForRole: input.machineForRole } : {}),
 	};
 	if (input.registerTools && input.nodeId !== "root") registerLegionTools(input.pi, { db: input.db, nodeId: input.nodeId, role: self?.role, settings: input.settings, cwd: input.cwd, runDir: input.runDir, eventBus, sendSelfMessage: (text: string) => notice(input.pi, text), ...(input.machine ? { machine: input.machine } : {}) });
 	postman.start();
@@ -623,8 +944,8 @@ function resolveLegionIdentity(input: {
 			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);
-		const machine = phaseMachineForRole(node.role, input.cwd, input.settings);
-		const identity = createLegionRuntime({ pi: input.pi, supervisor: input.supervisor, db, dbPath: absoluteDbPath, nodeId, rootRunId: getNode(db, "root")?.runId ?? path.basename(path.dirname(absoluteDbPath)), runDir: input.store.runDir(nodeRun.runId), cwd: input.cwd, storeRootDir: input.store.rootDir, settings: settingsForLegion(input.settings), eventBus: input.eventBus, registerTools: true, ...(machine ? { machine } : {}) });
+		const machine = phaseMachineForNode(node.role, input.cwd, input.settings);
+		const identity = createLegionRuntime({ pi: input.pi, supervisor: input.supervisor, db, dbPath: absoluteDbPath, nodeId, rootRunId: getNode(db, "root")?.runId ?? path.basename(path.dirname(absoluteDbPath)), runDir: input.store.runDir(nodeRun.runId), cwd: input.cwd, storeRootDir: input.store.rootDir, settings: settingsForLegion(input.settings), eventBus: input.eventBus, registerTools: true, ...(machine ? { machine } : {}), machineForRole: (role) => phaseMachineForRole(role, input.cwd, input.settings) });
 		// #273: `createLegionRuntime` runs during extension LOADING, where host
 		// actions (sendMessage, spawn, ui) are not available yet. Defer the team
 		// recovery to the next tick so a failure inside it cannot crash the load
@@ -680,22 +1001,207 @@ async function resumeLegionTeam(input: { identity: LegionRuntimeIdentity; input:
 			}
 		}
 		try {
-			await resumeLegionChild({ pi: input.input.pi, supervisor: input.input.supervisor, db: input.identity.db, dbPath: input.identity.dbPath, eventBus: input.identity.eventBus, settings: input.identity.settings, cwd: input.input.cwd, storeRootDir: input.identity.storeRootDir, parentNodeId: input.identity.nodeId, node, message: `Resume from saved session ${node.sessionFile} and continue interrupted work.` });
+			await resumeLegionChild({ pi: input.input.pi, supervisor: input.input.supervisor, db: input.identity.db, dbPath: input.identity.dbPath, eventBus: input.identity.eventBus, settings: input.identity.settings, cwd: input.input.cwd, storeRootDir: input.identity.storeRootDir, parentNodeId: input.identity.nodeId, node, message: `Resume from saved session ${node.sessionFile} and continue interrupted work.`, ...(input.identity.machineForRole ? { machineForRole: input.identity.machineForRole } : {}) });
 		} catch (error) { notice(input.input.pi, `Could not resume ${node.id}: ${error instanceof Error ? error.message : String(error)}`); }
 	}
 }
 
-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: currentProcessSpawnMode() } });
+function createRootLegion(input: { pi: ExtensionAPI; supervisor: LegionSupervisor; store: RunStore; cwd: string; task: string; settings: ReturnType<typeof loadSubagentSettings>; maxDepth: number; eventBus: LegionEventBus; rootSessionFile?: string | undefined }): LegionRuntimeIdentity {
+	// #374 §2: this session may already own a tree. Reopening it (same run, same
+	// ledger, same rows) is the whole point of the contract — a fresh run would
+	// build a SHADOW tree whose `legion_tree`, phases and mail are all detached
+	// from the ones the interrupted session left behind.
+	const reopened = reopenSessionRun(input);
+	if (reopened) return reopened;
+	const rootRun = input.store.createRun({ task: input.task, cwd: input.cwd, maxDepth: input.maxDepth, nodeId: "root", ...(input.rootSessionFile ? { sessionFile: input.rootSessionFile } : {}), herdr: { supervisor: currentProcessSpawnMode() } });
 	const dbPath = path.resolve(legionDbPath(input.store.runDir(rootRun.runId)));
 	const db = openLegionDb(dbPath);
 	const now = Date.now();
-	insertNode(db, { id: "root", parentId: null, name: "root", role: "root", kind: "pi", depth: 0, runId: rootRun.runId, status: "running", taskSummary: input.task.slice(0, 2_000), createdAt: now, updatedAt: now }, () => now);
+	// #322/#338 M1: record THIS session's file on the root row. The postman's
+	// DELIVERED evidence scan reads `nodes.session_file` per recipient, and the root
+	// node is a recipient (`to: "parent"` from a top-level centurion) — without
+	// this, every mail addressed to root sat at `ACCEPTED` forever. The child path
+	// writes the same column from `reserveNode`; this is the root equivalent.
+	insertNode(db, { id: "root", parentId: null, name: "root", role: "root", kind: "pi", depth: 0, runId: rootRun.runId, status: "running", taskSummary: input.task.slice(0, 2_000), ...(input.rootSessionFile ? { sessionFile: input.rootSessionFile } : {}), createdAt: now, updatedAt: now }, () => now);
 	appendEvent(db, "root", "node_launched", { runId: rootRun.runId, task: input.task }, { now: () => now });
-	return createLegionRuntime({ pi: input.pi, supervisor: input.supervisor, db, dbPath, nodeId: "root", rootRunId: rootRun.runId, runDir: input.store.runDir(rootRun.runId), cwd: input.cwd, storeRootDir: input.store.rootDir, settings: settingsForLegion(input.settings), eventBus: input.eventBus, registerTools: false });
+	return createLegionRuntime({ pi: input.pi, supervisor: input.supervisor, db, dbPath, nodeId: "root", rootRunId: rootRun.runId, runDir: input.store.runDir(rootRun.runId), cwd: input.cwd, storeRootDir: input.store.rootDir, settings: settingsForLegion(input.settings), eventBus: input.eventBus, registerTools: false, machineForRole: (role) => phaseMachineForRole(role, input.cwd, input.settings) });
+}
+
+/**
+ * #374 §1: the ONE session-identity judgement in this repo.
+ *
+ * Two processes belong to the same session iff their session transcript paths
+ * are the same file (`path.resolve`). There is no session-id concept here and
+ * none is invented — `ChildRecord.sessionId` is a dead field.
+ *
+ * A session with no transcript (`SessionManager.inMemory()` hands out
+ * `undefined`) has NO identity: nothing is recorded, nothing is found, nothing
+ * is resumed.
+ */
+export function findSessionRun(store: RunStore, sessionFile: string | undefined): RunRecord | undefined {
+	if (!sessionFile) return undefined;
+	const target = path.resolve(sessionFile);
+	let newest: RunRecord | undefined;
+	for (const run of store.listRuns()) {
+		if (typeof run.sessionFile !== "string") continue;
+		if (path.resolve(run.sessionFile) !== target) continue;
+		// `listRuns()` is oldest-first, but the ordering is the store's business:
+		// compare explicitly so "the most recent run of this session" is true by
+		// construction rather than by luck.
+		if (!newest || run.createdAt >= newest.createdAt) newest = run;
+	}
+	return newest;
+}
+
+/**
+ * Reopen the ledger of THIS session's previous run (#374 §2).
+ *
+ * Returns `undefined` whenever the situation is not a clean reopen — no session
+ * credential, no matching run, an unreadable/corrupt ledger, or a run whose root
+ * row is gone. Every one of those degrades to "behave exactly like today" (a
+ * new run), never to a throw: losing continuity must not cost the user a launch.
+ *
+ * Deliberately NOT written here: a new run record, a `node_launched` event, a
+ * second root row (`insertNode` would throw `NodeNameConflictError`), or any
+ * touch of the phase columns (§3 leaves them exactly where the pause left
+ * them).
+ */
+function reopenSessionRun(input: { pi: ExtensionAPI; supervisor: LegionSupervisor; store: RunStore; cwd: string; settings: ReturnType<typeof loadSubagentSettings>; eventBus: LegionEventBus; rootSessionFile?: string | undefined }): LegionRuntimeIdentity | undefined {
+	const sessionFile = input.rootSessionFile;
+	const previous = findSessionRun(input.store, sessionFile);
+	if (!previous) return undefined;
+	const dbPath = path.resolve(legionDbPath(input.store.runDir(previous.runId)));
+	let db: DatabaseSync | undefined;
+	try {
+		db = openLegionDb(dbPath);
+		if (!getNode(db, "root")) {
+			// A ledger without its root row is not a tree we can hand back.
+			db.close();
+			return undefined;
+		}
+	} catch (error) {
+		try { db?.close(); } catch { /* the open failed; nothing to release */ }
+		console.warn(
+			`[pi-legion] could not reopen the ledger of this session (${dbPath}): ${error instanceof Error ? error.message : String(error)}; starting a new run.`,
+		);
+		return undefined;
+	}
+	try {
+		const now = Date.now();
+		// The row exists: UPDATE it. `insertNode` would throw on the name conflict,
+		// and a second root row is not a thing this schema can hold.
+		updateNode(db, "root", { status: "running", ...(sessionFile ? { sessionFile: path.resolve(sessionFile) } : {}) }, () => now);
+		// §2: "不新写 run.json（只更新 updatedAt）" — every other field of the
+		// record is preserved verbatim, including the task the run was created for.
+		input.store.writeRun(previous);
+	} catch (error) {
+		try { db.close(); } catch { /* nothing to release */ }
+		console.warn(
+			`[pi-legion] could not adopt the previous run ${previous.runId}: ${error instanceof Error ? error.message : String(error)}; starting a new run.`,
+		);
+		return undefined;
+	}
+	reopenedSessionLedgers.add(dbPath);
+	return createLegionRuntime({ pi: input.pi, supervisor: input.supervisor, db, dbPath, nodeId: "root", rootRunId: previous.runId, runDir: input.store.runDir(previous.runId), cwd: input.cwd, storeRootDir: input.store.rootDir, settings: settingsForLegion(input.settings), eventBus: input.eventBus, registerTools: false, machineForRole: (role) => phaseMachineForRole(role, input.cwd, input.settings) });
 }
 
-async function resumeLegionChild(input: { pi: ExtensionAPI; supervisor: LegionSupervisor; db: DatabaseSync; dbPath: string; eventBus: LegionEventBus; settings: LegionSettings; cwd: string; storeRootDir: string; parentNodeId: string; node: LegionNode; message: string }): Promise<void> {
+/**
+ * Read-only probe used by `before_agent_start` before this entry owns a ledger.
+ *
+ * Mirrors what `reopenSessionRun` will accept — same run lookup, same "the root
+ * row must exist" gate — so the hint can never advertise continuity that the
+ * adoption would then refuse. A corrupt or absent ledger degrades to "nothing to
+ * report", never to a throw, and run.json is never written (invariant I1).
+ */
+function probeInterruptedNodes(store: RunStore, sessionFile: string): LegionNode[] {
+	const run = findSessionRun(store, sessionFile);
+	if (!run) return [];
+	const dbPath = path.resolve(legionDbPath(store.runDir(run.runId)));
+	if (!fs.existsSync(dbPath)) return [];
+	let db: DatabaseSync | undefined;
+	try {
+		db = openLegionDb(dbPath);
+		return getNode(db, "root") ? interruptedChildren(db) : [];
+	} catch {
+		return [];
+	} finally {
+		try { db?.close(); } catch { /* probe is best-effort */ }
+	}
+}
+
+/**
+ * #374 §5: the children a previous exit left behind, i.e. the ones this session
+ * may resume.
+ *
+ * Two ways a child counts as interrupted:
+ *  - it is still LIVE in the ledger (`starting`/`running`/`blocked`): its process
+ *    died with the session, so nothing will ever move it again;
+ *  - or it was paused by an exit: `retired` AND the last `node_retired` on it
+ *    carries `reason: "session-shutdown"` (§3 writes that). The reason matters —
+ *    a `retired` node without it was stopped deliberately (or finished), and
+ *    advertising it as "interrupted" would invite the agent to undo a user's
+ *    explicit stop.
+ *
+ * The phase is NOT part of the predicate: only teams that declare `phases:` get
+ * one (#371), so requiring a non-null phase would hide exactly the most common
+ * case — an interrupted worker. Resumability is checked separately by
+ * `childFromNode`, which refuses `failed`/terminal-phase nodes only.
+ *
+ * Only DIRECT children are listed. A name is resolvable from here only if this
+ * node is its parent (`subagent({action:"resume", name})` looks under the
+ * caller), so advertising a grandchild would name an action that cannot work;
+ * resuming the team brings its own squad back with it.
+ */
+export function interruptedChildren(db: DatabaseSync, parentNodeId = "root"): LegionNode[] {
+	const paused = new Set<string>();
+	const rows = db
+		.prepare(
+			"SELECT node_id, data FROM events WHERE type = 'node_retired' AND id IN " +
+				"(SELECT MAX(id) FROM events WHERE type = 'node_retired' GROUP BY node_id)",
+		)
+		.all() as Array<{ node_id: string; data: string | null }>;
+	for (const row of rows) {
+		let reason: unknown;
+		try {
+			reason = row.data ? (JSON.parse(row.data) as { reason?: unknown }).reason : undefined;
+		} catch {
+			reason = undefined;
+		}
+		if (reason === "session-shutdown") paused.add(row.node_id);
+	}
+	return getChildren(db, parentNodeId).filter((node) => {
+		if (isTerminalNode(node) || !node.sessionFile) return false;
+		if ((LIVE_CHILD_STATUSES as readonly string[]).includes(node.status)) return true;
+		return node.status === "retired" && paused.has(node.id);
+	});
+}
+
+/** The frozen §5 wording. Quoted, not paraphrased: it is the rule the agent must read. */
+export const INTERRUPTED_NODES_NOTE =
+	"These subagents were interrupted when the previous session exited.\n" +
+	"Do NOT resume them on your own; ask the user first, then call\n" +
+	"subagent({action:\"resume\", name}) for each one they approve.";
+
+/** How many interrupted nodes the prompt lists before it starts counting. */
+export const INTERRUPTED_NODES_PROMPT_CAP = 10;
+
+/**
+ * The system-prompt section for {@link interruptedChildren}, or `""` when there
+ * is nothing to report.
+ *
+ * Rendered fresh on every `before_agent_start`, so it DISAPPEARS by itself once
+ * the last listed node has been resumed or dropped — the section is a view of
+ * the ledger, never an accumulating log.
+ */
+export function renderInterruptedSection(nodes: readonly Pick<LegionNode, "name" | "phase">[]): string {
+	if (nodes.length === 0) return "";
+	const shown = nodes.slice(0, INTERRUPTED_NODES_PROMPT_CAP).map((node) => `- ${node.name} · ${node.phase ?? "<none>"}`);
+	const hidden = nodes.length - INTERRUPTED_NODES_PROMPT_CAP;
+	if (hidden > 0) shown.push(`- …and ${hidden} more`);
+	return `## Interrupted subagents\n\n${INTERRUPTED_NODES_NOTE}\n\n${shown.join("\n")}`;
+}
+
+async function resumeLegionChild(input: { pi: ExtensionAPI; supervisor: LegionSupervisor; db: DatabaseSync; dbPath: string; eventBus: LegionEventBus; settings: LegionSettings; cwd: string; storeRootDir: string; parentNodeId: string; node: LegionNode; message: string; machineForRole?: (role: string | null | undefined) => PhaseMachine | undefined }): Promise<void> {
 	const parent = getNode(input.db, input.parentNodeId);
 	if (!parent || !input.node.runId || !input.node.sessionFile) throw new Error(`resume credentials missing for ${input.node.id}`);
 	const store = new RunStore({ rootDir: input.storeRootDir });
@@ -733,9 +1239,9 @@ async function resumeLegionChild(input: { pi: ExtensionAPI; supervisor: LegionSu
 	const childRun = store.readRun(input.node.runId);
 	if (!childRun) throw new Error(`child run.json not found: ${input.node.runId}`);
 	const parentOfSupervisor = parent.parentId ? getNode(input.db, parent.parentId) : null;
-	const orchestrator = new Orchestrator({ supervisor: input.supervisor, runDir: store.runDir(parentRun.runId), cwd, maxDepth: catalog.settings.legion?.maxDepth, maxSpawns: catalog.settings.maxSubagentSpawnsPerSession ?? null, team: resumedTeam.team, childContext: resolveTeamContext("child", catalog.settings, resumedTeam.team), parentPath: parentRun.path, ...rpcApproveFrom(catalog.settings), launchQueue: launchQueueBounds(catalog.settings), onLaunchQueueNotice: launchQueueNoticeSink(input.pi), legion: { db: input.db, dbPath: input.dbPath, nodeId: parent.id, parentNodeId: parent.parentId, parentRunId: parentOfSupervisor?.runId ?? null, runId: parentRun.runId, runStore: store, settings: input.settings, eventBus: input.eventBus } });
+	const orchestrator = new Orchestrator({ supervisor: input.supervisor, runDir: store.runDir(parentRun.runId), cwd, maxDepth: catalog.settings.legion?.maxDepth, maxSpawns: catalog.settings.maxSubagentSpawnsPerSession ?? null, team: resumedTeam.team, childContext: resolveTeamContext("child", catalog.settings, resumedTeam.team), parentPath: parentRun.path, ...rpcApproveFrom(catalog.settings), launchQueue: launchQueueBounds(catalog.settings), onLaunchQueueNotice: launchQueueNoticeSink(input.pi), legion: { db: input.db, dbPath: input.dbPath, nodeId: parent.id, parentNodeId: parent.parentId, parentRunId: parentOfSupervisor?.runId ?? null, runId: parentRun.runId, runStore: store, settings: input.settings, eventBus: input.eventBus, ...(input.machineForRole ? { machineForRole: input.machineForRole } : {}) } });
 	orchestrator.restore(parentRun);
-	const handle = await orchestrator.launch({ agent, task: input.message, name: saved.name, ...(input.node.team ? { team: input.node.team } : {}), ...(saved.model ? { model: saved.model } : {}), worktree: Boolean(saved.worktreePath) });
+	const handle = await orchestrator.launch({ agent, task: input.message, name: saved.name, ...(input.node.team ? { team: input.node.team } : {}), ...(saved.model ? { model: saved.model } : {}), ...(saved.phases ? { phases: saved.phases } : {}), worktree: Boolean(saved.worktreePath) });
 	await store.updateChild(parentRun.runId, saved.name, (child) => Object.assign(child, handle.child));
 }
 
@@ -784,6 +1290,16 @@ async function resumeLegionChild(input: { pi: ExtensionAPI; supervisor: LegionSu
 const legionIdentityKey = (dbPath: string, nodeId: string): string => `${dbPath}\u0000${nodeId}`;
 const legionIdentities = new Map<string, LegionRuntimeIdentity>();
 
+/**
+ * Ledgers THIS process reopened because the session had been here before (#374).
+ *
+ * The §5 prompt hint is scoped to them on purpose: a fresh tree has nothing
+ * interrupted to report, and a tree adopted through `PI_LEGION_DB` env belongs to
+ * a live or being-resumed session, not to a restart. Keyed by resolved ledger
+ * path, like {@link legionIdentities}.
+ */
+const reopenedSessionLedgers = new Set<string>();
+
 export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps = {}) {
 	// #197 D8: a session is a child if either transport says so. RPC children
 	// are separate processes marked in env; in-process children share the
@@ -1055,6 +1571,18 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 	const pendingUtilityRetires: Array<(opts?: RetireOptions) => Promise<void>> = [];
 	let sessionRuntime: SessionRuntime | undefined;
 	const shutdownRetireAll = async (_event?: unknown, ctx?: { mode?: string }): Promise<void> => {
+		// #374 §3: record what this exit interrupts BEFORE anything drains or kills.
+		// `--print`/`--json` drain first, and a child whose turn ends during that drain
+		// (including one the exit just killed) parses as a finished turn and would be
+		// recorded `settled/success` — the interrupt would be lost. The marker only
+		// writes the ledger, so a child that genuinely finishes during the drain still
+		// ends up `settled` (measured in the container before this line existed).
+		const own = ownLegionIdentity();
+		if (own) {
+			try {
+				markSessionInterrupted(own.db, own.nodeId, () => Date.now());
+			} catch { /* the ledger may already be closing; never block shutdown */ }
+		}
 		// #181: short --print exits before the deferred timer; flush now so
 		// orphan rpc-child-* dirs still get swept on a clean exit.
 		if (!isChild) flushHygieneIfPending();
@@ -1122,6 +1650,44 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 			},
 		});
 	}
+	/**
+	 * #374 §5: what THIS session's previous run left interrupted, for the prompt.
+	 *
+	 * Two sources, one predicate. Once this entry owns a ledger it is read live, so
+	 * a recovered or dropped node leaves the section on the very next turn. Before
+	 * that — which is the FIRST prompt of a reopened session, because the tree is
+	 * only adopted when a launch needs it — the same lookup `createRootLegion`
+	 * will use runs READ-ONLY: `findSessionRun` on this session's own transcript
+	 * path, then that run's ledger. Memoized, so one scan per session at most.
+	 *
+	 * A session with no transcript path has no identity (§1) and never looks at
+	 * anything; a different session's runs are never matched, so they are never
+	 * read, hinted at or touched (invariant I1).
+	 */
+	let continuityProbe: { key: string; nodes: LegionNode[] } | undefined;
+	/** Same startup, one notice (§5). Keyed like {@link continuityProbe}. */
+	const continuityNotified = new Set<string>();
+	const sessionContinuity = (ctx: Pick<ExtensionContext, "cwd"> & { sessionManager?: { getSessionFile?: () => string | undefined } } | undefined): { key: string; nodes: LegionNode[] } | undefined => {
+		// A node THIS process is running right now is not interrupted, whatever its
+		// row still says (`resume` flips it to `running`, which §5's status set
+		// contains). Liveness is the one fact the ledger cannot answer, and without
+		// it the section would keep nagging about a team that was just recovered.
+		const interrupted = (nodes: LegionNode[]): LegionNode[] => nodes.filter((node) => !supervisor.isAlive(node.name));
+		const own = ownLegionIdentity();
+		if (own) {
+			const key = path.resolve(own.dbPath);
+			// Only a session that REOPENED its own run reports anything; a tree adopted
+			// through env belongs to a session that is still live (or being resumed).
+			return reopenedSessionLedgers.has(key) ? { key, nodes: interrupted(interruptedChildren(own.db)) } : undefined;
+		}
+		const sessionFile = ctx?.sessionManager?.getSessionFile?.();
+		if (!sessionFile) return undefined;
+		const key = path.resolve(sessionFile);
+		if (continuityProbe?.key === key) return continuityProbe;
+		const store = runStoreFor(ctx?.cwd ?? lastCwd);
+		continuityProbe = { key, nodes: interrupted(probeInterruptedNodes(store, key)) };
+		return continuityProbe;
+	};
 	pi.on("before_agent_start", (event, ctx) => {
 		if (process.env[UTILITY_CHILD_ENV] === "1") return;
 		if (!subagentsEnabled(ctx?.cwd ?? lastCwd)) return;
@@ -1143,12 +1709,37 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 		const rosterAgents = selfRole
 			? catalog.agents.filter((agent) => agent.name !== selfRole)
 			: catalog.agents;
+		// #374 §5: the same session coming back finds its paused children named here.
+		// The section is derived from the ledger on every prompt, so it vanishes by
+		// itself once nothing is left to resume (idempotent, never accumulating).
+		const continuity = sessionContinuity(ctx);
+		const interrupted = continuity ? renderInterruptedSection(continuity.nodes) : "";
+		if (continuity && continuity.nodes.length > 0) {
+			// One notice per STARTUP, not per turn. Keyed by the session transcript when
+			// there is one, because the same session is described by two different
+			// handles over its life (the read-only probe before adoption, the live
+			// ledger after it) and both must count as "the same startup".
+			const sessionFile = ctx?.sessionManager?.getSessionFile?.();
+			const noticeKey = sessionFile ? path.resolve(sessionFile) : continuity.key;
+			if (!continuityNotified.has(noticeKey)) {
+				continuityNotified.add(noticeKey);
+				const count = continuity.nodes.length;
+				try {
+					ctx?.ui?.notify?.(
+						`pi-legion: ${count} subagent${count === 1 ? "" : "s"} from this session were interrupted when it exited — nothing was restarted. Ask me to resume the ones you want.`,
+						"info",
+					);
+				} catch {
+					// no UI (print mode / headless): the prompt section still carries the fact
+				}
+			}
+		}
 		return {
 			systemPrompt: `${event.systemPrompt}\n\n${PARENT_PLAYBOOK}\n\n${renderParentRoster(
 				rosterAgents,
 				catalog.team,
 				catalog.teamWarnings,
-			)}${parentContext ? `\n\n${parentContext}` : ""}`,
+			)}${parentContext ? `\n\n${parentContext}` : ""}${interrupted ? `\n\n${interrupted}` : ""}`,
 		};
 	});
 	if (process.env[UTILITY_CHILD_ENV] === "1") {
@@ -1200,6 +1791,13 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 				return machine;
 			};
 		})(),
+		// #372 B: /legion must show the machine an inline-declared team was
+		// DISPATCHED with (`subagent({ phases })`, #371 §2). That declaration has no
+		// card to look up, so it is answered per NODE from the dispatching run's
+		// run.json — the one source that survives a reload, a later process and a
+		// reopened session. The caching and the run plumbing live in the factory so
+		// they can be tested without booting the extension (#372 review, minor 1).
+		getPhaseMachineForNode: createInlineMachineLookup({ cwd: () => lastCwd, runStoreFor }),
 		getTreeIdentity: (name) => {
 			const own = ownLegionIdentity();
 			const node = own && getChildByName(own.db, own.nodeId, name);
@@ -1365,7 +1963,10 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 				// uses: `alive` is this process's in-memory registry and never holds a
 				// child launched elsewhere, so a foreign record needs the owner marker.
 				// Undefined while alive — liveness already wins there.
-				const owner = ownerVerdictFor(store, runs, child.name, alive);
+				const owner = ownerVerdictFor(store, () => runs, child.name, alive);
+				// #315/#331: same display-only activity fact `subagent status` prints,
+				// so the slash command cannot drift from the tool surface.
+				const inFlightTools = inFlightToolStackOf(supervisor, child.name);
 				return {
 					name: child.name,
 					state: child.state,
@@ -1381,6 +1982,7 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 					...(child.spawnMode ? { spawnMode: child.spawnMode } : {}),
 					alive,
 					...(owner ? { owner } : {}),
+					...(inFlightTools ? { inFlightTools } : {}),
 				};
 			} catch {
 				return undefined;
@@ -1515,7 +2117,15 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 				activeLegion = resolveLegionIdentity({ pi, supervisor, store, cwd, settings, eventBus: legionBus, cached: ownLegionIdentity(), sessionFile: ctx.sessionManager?.getSessionFile() });
 				if (!activeLegion && action === "launch" && !isChild) {
 					const plan = buildPlan(params);
-					if (plan.ok) activeLegion = createRootLegion({ pi, supervisor, store, cwd, task: plan.task, settings, maxDepth: effectiveMaxDepth(settings.legion?.maxDepth), eventBus: legionBus });
+					if (plan.ok) activeLegion = createRootLegion({ pi, supervisor, store, cwd, task: plan.task, settings, maxDepth: effectiveMaxDepth(settings.legion?.maxDepth), eventBus: legionBus, rootSessionFile: ctx.sessionManager?.getSessionFile() });
+				} else if (!activeLegion && !isChild && (action === "resume" || action === "continue")) {
+					// #374 §4/§7-2: a resume is the ONE control action that must act on the
+					// reopened tree. Without the adoption `input.legion.nodeId` is unknown to
+					// the launcher and the child would restart OUTSIDE the ledger — visibly
+					// running while its `nodes` row stayed `retired`. Reopen-ONLY: when this
+					// session owns no previous run the call falls through to today's behaviour
+					// (no tree is invented, nothing is written).
+					activeLegion = reopenSessionRun({ pi, supervisor, store, cwd, settings, eventBus: legionBus, rootSessionFile: ctx.sessionManager?.getSessionFile() });
 				}
 				if (activeLegion) adoptLegionIdentity(activeLegion);
 			} catch (error) {
@@ -1549,7 +2159,7 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 					legion: activeLegion,
 				});
 				if (signal?.aborted && action !== "stop") {
-					return ok("interrupted (parent turn ended; children still running)");
+					return interruptedControlResult({ result, runtime, legion: activeLegion });
 				}
 				return result;
 			}
@@ -1601,12 +2211,28 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 	});
 
 	const bindUi = (_event: unknown, ctx: ExtensionContext): void => {
-		lastUi = ctx.hasUI ? ctx.ui : undefined;
-		if (ctx.cwd) lastCwd = ctx.cwd;
+		// #377: `session.dispose()` invalidates the extension ctx, but the run's
+		// `finally` still dispatches `turn_end` / `agent_settled`. Reading `hasUI` on
+		// that ctx throws, and the host prints "Extension error (/plugin/index.ts)" at
+		// every exit. The board already treats staleness as "no UI"; the handler entry
+		// has to answer the same way instead of throwing.
+		let ui: ExtensionContext["ui"] | undefined;
+		let hasUi = false;
+		try {
+			hasUi = ctx.hasUI;
+			ui = hasUi ? ctx.ui : undefined;
+			if (ctx.cwd) lastCwd = ctx.cwd;
+		} catch (error) {
+			if (!isStaleUiError(error)) throw error;
+			lastUi = undefined;
+			lastConfirm = undefined;
+			return;
+		}
+		lastUi = ui;
 		runtime.bind(ctx);
 		lastConfirm =
-			ctx.hasUI && typeof ctx.ui?.confirm === "function"
-				? (message) => ctx.ui.confirm("", message)
+			hasUi && typeof ui?.confirm === "function"
+				? (message) => ui!.confirm("", message)
 				: undefined;
 	};
 
@@ -1667,9 +2293,21 @@ export default function piLegion(pi: ExtensionAPI, deps: ExtensionSupervisorDeps
 	pi.on("turn_start", (event, ctx) => {
 		bindUi(event, ctx);
 	});
-	pi.on("turn_end", (event, ctx) => {
-		bindUi(event, ctx);
-	});
+	// Deliberately NOT `pi.on("turn_end", ...)`.
+	//
+	// The host's turn-end boundary (`_dispatchTurnEndBoundary`) only exists to feed
+	// `turn_end` handlers, and it is also where it emits "turn_end could not resolve
+	// the persisted assistant entry ID" — a message it can only produce when
+	// `hasHandlers("turn_end")` is true, because the gate is checked before the
+	// missing-entry case. A turn that ends after `dispose()` aborted it (session
+	// exit with a wake turn in flight, `notice()`'s `triggerTurn`) is exactly that
+	// case, and no amount of care on our side persists that message.
+	//
+	// Registering `turn_end` bought us one extra `bindUi`, and `bindUi` already runs
+	// on turn_start, agent_start, agent_end, agent_settled, input, tool_result and
+	// session_info_changed — the next event re-binds the current ctx anyway. Dropping
+	// it removes the host's only reason to run the boundary, so the line is never
+	// printed. If someone needs a turn-scoped refresh later, use `turn_start`.
 	pi.on("agent_start", (event, ctx) => {
 		runtime.notifyParentRunStart();
 		bindUi(event, ctx);
@@ -1753,6 +2391,14 @@ export function loadCatalog(
 	};
 }
 
+/**
+ * #384: the inbox the blocking tools watch, or `undefined` when this call is not a
+ * legion node (a plain session keeps `wait`/`collect` exactly as they were — I1).
+ */
+function mailSeamOf(legion: OrchestratorLegionContext | undefined): MailReleaseSeam | undefined {
+	return legion ? { db: legion.db, nodeId: legion.nodeId } : undefined;
+}
+
 /**
  * Act on an EXISTING child: status, steer, collect, retire, continue, resume.
  *
@@ -1806,6 +2452,7 @@ async function controlAction(input: {
 			allAgents: input.allAgents,
 			store,
 			cwd,
+			mail: mailSeamOf(input.legion),
 		});
 	}
 
@@ -1816,34 +2463,50 @@ async function controlAction(input: {
 			params,
 			runtime: input.runtime,
 			store: input.store,
-			retire: async (name, opts) => {
+			// #312: the run this call is scoped to — the explicit `runId`, else the
+			// run this session owns. `stopAction` resolves the name inside it only.
+			runId: params.runId,
+			sessionRunId: input.legion?.runId,
+			retire: async (name, opts, scope) => {
 				const merged = opts ?? retireOpts;
 				const job = input.runtime.get(name);
-				if (job?.retire) {
+				// #312: a live job is a node of exactly ONE run. Retire it only when the
+				// scope agrees (or the caller named no run) — a same-named job in another
+				// run is a different node, and stopping it would retire a child that was
+				// never reported.
+				if (job?.retire && (scope?.runId === undefined || job.runId === scope.runId)) {
 					await job.retire(merged);
 					return;
 				}
-				// A completion watch can retire/release a target after stop snapshots
-				// all names but before the serial loop reaches it. Treat that target as
-				// stopped; only rebuild if its persisted record is not already retired.
-				const found = findChild(input.store.listRuns(), name);
-				if (!found) throw unknownChildError(name);
-				if (found.child.state === "retired") return;
+				// The persisted record is read in the SAME run `stopAction` resolved the
+				// name in — never re-resolved across runs (`pickChildByName` prefers a live
+				// then the newest record), which is how `stop` came to REPORT this session's
+				// `worker-0` and RETIRE another run's live one.
+				//
+				// A completion watch can retire/release a target after stop snapshots all
+				// names but before the serial loop reaches it. Treat a vanished or already
+				// retired target as stopped; only rebuild the orchestrator when there is
+				// still something to retire.
+				const runId = scope?.runId;
+				const run = runId ? input.store.readRun(runId) : null;
+				const child = run?.children.find((candidate) => candidate.name === name);
+				if (!runId || !run || !child) throw unknownChildError(name);
+				if (child.state === "retired") return;
 				const orchestrator = new Orchestrator({
 					supervisor: input.supervisor,
 					uiProxy: input.uiProxy,
-					runDir: input.store.runDir(found.runId),
+					runDir: input.store.runDir(runId),
 					cwd: input.cwd,
 					maxDepth: input.settings.legion?.maxDepth,
 					childContext: resolveTeamContext("child", input.settings, input.team),
 					...teamForChildren(input.team),
 					...rpcApproveFrom(input.settings),
-					...(input.legion ? { legion: { ...input.legion, runId: found.runId, runStore: input.store } } : {}),
+					...(input.legion ? { legion: { ...input.legion, runId, runStore: input.store } } : {}),
 					onBudgetRefused: input.onBudgetRefused,
 				});
-				orchestrator.restore(found.run);
+				orchestrator.restore(run);
 				await orchestrator.retire(name, merged);
-				await persistChild(input.store, found.runId, orchestrator, name);
+				await persistChild(input.store, runId, orchestrator, name);
 			},
 		});
 	}
@@ -1861,42 +2524,94 @@ async function controlAction(input: {
 			// Liveness facts are read once per name and reused by both the filter and
 			// the block, so `status` cannot classify a child one way and render it
 			// another (display-liveness D6 exit 1).
-			const factsByName = new Map<string, StatusLivenessFacts & { pid?: number }>();
-			const factsFor = (child: StatusChildRecord): StatusLivenessFacts & { pid?: number } => {
+			const factsByName = new Map<string, StatusLivenessFacts & { pid?: number; inFlightTools?: InFlightToolStack }>();
+			const factsFor = (child: StatusChildRecord): StatusLivenessFacts & { pid?: number; inFlightTools?: InFlightToolStack } => {
 				const cached = factsByName.get(child.name);
 				if (cached) return cached;
 				const alive = input.supervisor.isAlive(child.name);
-				const owner = ownerVerdictFor(store, runs, child.name, alive);
+				const owner = ownerVerdictFor(store, () => runs, child.name, alive);
 				// A pid only exists for a child this process actually tracks; a
 				// record from another session has none, and none is invented.
 				const pid = input.runtime.get(child.name)?.pid;
-				const facts = { alive, ...(owner ? { owner } : {}), ...(pid ? { pid } : {}) };
+				// #315/#331: same rule for the in-flight stack — only this process's
+				// live backend can answer, and `undefined` renders no line.
+				const inFlightTools = inFlightToolStackOf(input.supervisor, child.name);
+				const facts = {
+					alive,
+					...(owner ? { owner } : {}),
+					...(pid ? { pid } : {}),
+					...(inFlightTools ? { inFlightTools } : {}),
+				};
 				factsByName.set(child.name, facts);
 				return facts;
 			};
 			const classified = classifyChildrenForStatus(runs, factsFor);
+			const now = Date.now();
 			return ok(
 				renderStatusOverview(
 					classified.map(({ child, live }) => {
-						const { pid, ...facts } = factsFor(child);
-						return { child, ...facts, ...(pid ? { pid } : {}), live };
+						const { pid, inFlightTools, ...facts } = factsFor(child);
+						return {
+							child,
+							...facts,
+							...(pid ? { pid } : {}),
+							...(inFlightTools ? { inFlightTools } : {}),
+							live,
+						};
 					}),
+					now,
 				),
 			);
 		}
-		const runs = store.listRuns();
+		// #344: the registry scan is a FALLBACK, not an entry fee. A name this
+		// session is scoped to resolves from one `readRun`; the scan only happens
+		// when the answer depends on other runs.
+		const directRunId = scopeRunIdFor({
+			runId: params.runId,
+			sessionRunId: input.legion?.runId,
+			trackedRunId: input.runtime.get(params.name)?.runId,
+		});
+		const scope = resolveScopedChild({
+			name: params.name,
+			explicitRunId: params.runId,
+			directRunId,
+			readRun: (runId) => store.readRun(runId),
+			listRuns: () => store.listRuns(),
+		});
+		const hit = scope.hit;
+		// #312: `status` is the one action that may SHOW a node it does not own, but
+		// two same-named nodes are an ambiguity it must not resolve by preference —
+		// that preference is how `status` and `collect` came to disagree.
+		if (hit.kind === "elsewhere" && hit.candidates.length > 1) {
+			return fail(ambiguousChildMessage("status", params.name, hit.candidates), ErrorCodes.NOT_FOUND);
+		}
 		// #270: a miss in this store is not a miss overall — a worktree child's
 		// record lives under its own store, which this one cannot enumerate.
-		const found = findChild(runs, params.name) ?? findChildAcrossStores({
+		const found = scope.found ?? findChildAcrossStores({
 			name: params.name,
 			cwd,
 			callerCwd: input.callerCwd,
 			ownRoot: store.rootDir,
 		});
 		if (!found) return unknownChild(params.name, store, cwd, input.callerCwd);
+		// #312: when the record is not this session's own child, say which run it
+		// came from. A direct hit adds nothing — the existing output is unchanged.
+		//
+		// Only an `elsewhere` hit is a foreign record. `absent` means the name is in
+		// no run this store can enumerate and `found` came from the #270 cross-store
+		// lookup — often a child of THIS session whose worktree store is elsewhere,
+		// which this note would have mislabelled as "not a direct child".
+		const resolvedNote =
+			hit.kind === "elsewhere"
+				? `resolved: ${params.name} is not a direct child of this session — showing the record from run ${found.runId}`
+				: undefined;
 		const alive = input.supervisor.isAlive(params.name);
-		const owner = ownerVerdictFor(store, runs, params.name, alive);
-		return ok(renderLiveChildStatus({
+		// #312: the owner verdict belongs to the run dir of the record just resolved
+		// (`found.runId`) — not to whatever `pickChildByName` prefers across runs.
+		const owner = ownerVerdictFor(store, scope.runs, params.name, alive, found.runId);
+		// #315: what it is doing and for how long, prepended to the block when this
+		// process is actually running a tool for it.
+		const snapshot = renderLiveChildStatus({
 			name: found.child.name,
 			state: found.child.state,
 			agent: found.child.agent,
@@ -1907,7 +2622,10 @@ async function controlAction(input: {
 			spawnMode: found.child.spawnMode,
 			alive,
 			...(owner ? { owner } : {}),
-		}));
+		});
+		const inFlightTools = inFlightToolStackOf(input.supervisor, found.child.name);
+		const rendered = withInFlightToolLine(snapshot, inFlightTools, Date.now());
+		return ok(resolvedNote ? `${resolvedNote}\n${rendered}` : rendered);
 	}
 
 	if (!params.name) {
@@ -1917,8 +2635,45 @@ async function controlAction(input: {
 		);
 	}
 
+	// #344: as in `status`, the full registry is the FALLBACK. Resolving a name
+	// this call is already scoped to costs one `readRun` (0.05ms) instead of a
+	// scan of every run ever written (26ms at 352 runs).
+	const directRunId = scopeRunIdFor({
+		runId: params.runId,
+		sessionRunId: input.legion?.runId,
+		trackedRunId: input.runtime.get(params.name)?.runId,
+	});
+	const scope = resolveScopedChild({
+		name: params.name,
+		explicitRunId: params.runId,
+		directRunId,
+		readRun: (runId) => store.readRun(runId),
+		listRuns: () => store.listRuns(),
+	});
+	const hit = scope.hit;
+	if (hit.kind === "elsewhere") {
+		// #312: never guess between two same-named nodes, whichever action asked.
+		if (hit.candidates.length > 1) {
+			return fail(ambiguousChildMessage(action, params.name, hit.candidates), ErrorCodes.NOT_FOUND);
+		}
+		// `collect`/`continue` are defined over this session's direct children only,
+		// so a same-named node elsewhere is a refusal that names the candidates —
+		// not the old silent adoption of whatever `pickChildByName` preferred.
+		//
+		// Only when a scope EXISTS: a session with no run of its own has no direct
+		// children to protect, and #209-3 keeps that path reaching a foreign/
+		// restarted run's persisted record (the pre-existing contract tests build
+		// exactly that store, with no launch in this session at all). The bug #312
+		// describes needs a session run whose name resolution was overridden.
+		if (directRunId !== undefined && STRICT_SCOPE_ACTIONS.has(action)) {
+			return fail(notDirectChildMessage(action, params.name, hit.candidates), ErrorCodes.NOT_FOUND);
+		}
+	}
+	// `steer`/`abort`/`retire` keep their pre-#312 reach (one unambiguous record
+	// outside this session's run stays addressable); the scope run is still tried
+	// first, so the common case never depends on the fallback.
 	const found =
-		findChild(store.listRuns(), params.name) ??
+		scope.found ??
 		findChildAcrossStores({
 			name: params.name,
 			cwd,
@@ -1952,7 +2707,8 @@ async function controlAction(input: {
 	};
 
 	if (action === "steer") return steerChild(ctx);
-	if (action === "collect") return collectChild(ctx, input.signal);
+	if (action === "abort") return abortChild(ctx);
+	if (action === "collect") return collectChild(ctx, input.signal, mailSeamOf(input.legion));
 	if (action === "retire") return retireChild(ctx);
 	if (action === "continue" || action === "resume") return reviveChild(ctx);
 
@@ -2015,37 +2771,315 @@ function unknownChild(
 	);
 }
 
-/** Send a message to a running child without waiting for its reply. */
-async function steerChild(
+/**
+ * The run a named control call is scoped to (#312).
+ *
+ * Three sources, in the order the caller can be sure of them:
+ *
+ *   1. `runId` on the call itself — the explicit scope, which wins over every
+ *      inference (that is the escape hatch the refusal messages point at);
+ *   2. the run this session owns, from its legion identity: every child this
+ *      session launched outside a worktree record belongs here;
+ *   3. the run the runtime is currently tracking the name under — the window
+ *      where no legion identity resolves (a reloaded extension, a resumed run)
+ *      but the child is still live and known to this process.
+ *
+ * `undefined` is a real answer: no scope means nothing is a direct child, so a
+ * same-named record elsewhere is reported instead of silently adopted.
+ */
+function scopeRunIdFor(input: {
+	runId?: string | undefined;
+	sessionRunId?: string | undefined;
+	trackedRunId?: string | undefined;
+}): string | undefined {
+	return input.runId ?? input.sessionRunId ?? input.trackedRunId;
+}
+
+/** Actions that may only ever act on this session's own direct child (#312). */
+const STRICT_SCOPE_ACTIONS = new Set(["collect", "continue", "resume"]);
+
+/**
+ * Two or more same-named nodes and not one of them is this session's child.
+ *
+ * Never resolved by preference: the incident behind #312 is exactly what a
+ * "prefer the live one, then the newest" tie-break produces. The candidates are
+ * printed so the caller can name the run it meant.
+ */
+function ambiguousChildMessage(
+	action: string,
+	name: string,
+	candidates: readonly ChildScopeCandidate[],
+): string {
+	return (
+		`${name} is ambiguous: ${candidates.length} nodes carry that name and none of them is a direct child of this session, so \`${action}\` will not guess.\n` +
+		describeChildScopeCandidates(candidates) +
+		"\nPass `runId` to name the run that holds the one you mean."
+	);
+}
+
+/**
+ * Refuse an action whose contract is "this session's direct child" (#312).
+ *
+ * `collect` used to reach into whatever run `pickChildByName` preferred, which
+ * is how a parent chasing its own FAILED `worker-0` was handed another run's
+ * SUCCESSFUL one — the silent wrong node. The candidates are named so the caller
+ * can either pass `runId` or go through the node's parent instead.
+ */
+function notDirectChildMessage(
+	action: string,
+	name: string,
+	candidates: readonly ChildScopeCandidate[],
+): string {
+	return (
+		`${name} is not a direct child of this session, so \`${action}\` cannot act on it. ` +
+		`${candidates.length} node(s) carry that name:\n` +
+		describeChildScopeCandidates(candidates) +
+		`\n\`${action}\` only acts on this session's direct children; pass \`runId\`, or address the node through its parent's scope, to reach a grandchild.`
+	);
+}
+
+/**
+ * The parenthetical a queued steer carries (#313 D5).
+ *
+ * One constant on purpose: `steerReceipt` renders it for the `steer` tool and
+ * the revive/continue branch reuses it for a live child, so the queue wording
+ * exists exactly once.
+ */
+export const STEER_QUEUED_NOTE =
+	"queued — it takes effect after its current tool batch finishes";
+
+/** The same, for a steer an input handler swallowed before it was ever queued. */
+export const STEER_INTERCEPTED_NOTE =
+	"intercepted by an input handler — the child never saw it";
+
+/**
+ * Render the receipt for one accepted `steer` (#313 D5).
+ *
+ * The only place a steer receipt is built. The three dispositions are the only
+ * three things a caller can honestly claim, and there is no "delivered":
+ *
+ * - `queued`: Pi consumes a steer after the child's current tool batch finishes
+ *   and before its next LLM call, so a message sent into a running tool says
+ *   nothing about the model having seen it yet. Not an error, and it must not
+ *   read like one — but it must not read as success either.
+ * - `accepted`: the child was idle, so this call started a turn with the text.
+ *   The model still has to read it; this only says the session took the turn.
+ * - `intercepted`: an input handler ate the text before the queue. The child
+ *   never sees it, so the receipt must not open with "Steered".
+ */
+export function steerReceipt(
+	name: string,
+	disposition: SteerDisposition,
+): string {
+	if (disposition === "intercepted") {
+		return `Steer ${name} was ${STEER_INTERCEPTED_NOTE}`;
+	}
+	if (disposition === "accepted") {
+		return `Steered ${name} (a turn was started with it)`;
+	}
+	return `Steered ${name} (${STEER_QUEUED_NOTE})`;
+}
+
+/**
+ * Send a message to a running child without waiting for its reply.
+ *
+ * Exported so `test/unit/steer-receipt.test.ts` can drive the receipt end to
+ * end (same reason as `waitAction`/`stopAction`).
+ */
+export async function steerChild(
 	ctx: ChildContext,
 ): Promise<AgentToolResult<unknown>> {
 	if (!ctx.params.message) {
 		return fail("`message` is required for steer.", ErrorCodes.INVALID_PARAMS);
 	}
 	try {
-		await ctx.orchestrator.steer(ctx.name, ctx.params.message);
+		// Await into a local so the existing `followChild` call keeps its place
+		// between the steer and the receipt; the receipt itself is still
+		// `ok(steerReceipt(...))` with the disposition this steer reported.
+		const disposition = await ctx.orchestrator.steer(
+			ctx.name,
+			ctx.params.message,
+		);
 		followChild(ctx, { watch: true });
-		return ok(`Steered ${ctx.name}.`);
+		return ok(steerReceipt(ctx.name, disposition));
 	} catch (error) {
 		return fail(`steer failed: ${String(error)}`, ErrorCodes.NOT_FOUND);
 	}
 }
 
-/** Wait for the child's current turn and derive its outcome from the session. */
-async function collectChild(
+/**
+ * Render the receipt for one `abort` (#314 D7).
+ *
+ * The bounded wait the `timeout` receipt names comes from `outcome.timeoutMs` —
+ * the bound the backend actually applied — and NOT from a default of this
+ * function's own (#325). The tool surface never passes a `timeoutMs` (it stays a
+ * `wait`-only parameter), so a local default would be a second, silent source of
+ * truth: a caller that arms a different bound on the supervisor would still read
+ * "within 5s" here.
+ *
+ * All three statuses are honest outcomes of a *soft* interrupt, and none of
+ * them is a failure:
+ *
+ * - `interrupted`: the turn was cut short. Its context survives (the session is
+ *   not retired), but whatever the interrupted tool had already written to disk
+ *   stays written — a receipt that only promised "context kept" would let a
+ *   caller assume a clean rollback.
+ * - `no-turn`: nothing was running, so nothing was done. Saying "aborted" here
+ *   would claim an interrupt that never happened.
+ * - `timeout`: the abort was sent but the child had not settled inside the
+ *   bounded wait. A tool that ignores cancellation looks exactly like this, so
+ *   the receipt points at `stop` instead of pretending the turn died.
+ */
+export function abortReceipt(
+	name: string,
+	outcome: AbortOutcome,
+): string {
+	if (outcome.status === "no-turn") {
+		return `Nothing to abort: ${name} is not running a turn.`;
+	}
+	if (outcome.status === "timeout") {
+		const timeoutMs = outcome.timeoutMs;
+		const seconds = timeoutMs % 1000 === 0 ? String(timeoutMs / 1000) : (timeoutMs / 1000).toFixed(1);
+		return `Abort sent to ${name}, but it had not settled within ${seconds}s — the running tool may ignore cancellation; use stop (or stop with force) if it must die.`;
+	}
+	const dropped = outcome.cleared.steering + outcome.cleared.followUp;
+	const base = `Aborted ${name}'s current turn (context kept; partial edits may remain)`;
+	return dropped > 0 ? `${base} — dropped ${dropped} queued message(s)` : base;
+}
+
+/**
+ * Interrupt a child's current turn without tearing the child down (#314 D7).
+ *
+ * The child keeps its session and context, so it stays continuable — that is
+ * the whole difference from `stop`, which retires the process. Deliberately no
+ * `followChild` here: abort must not register a new watch (the child is already
+ * tracked and settles through its existing one).
+ *
+ * Exported so `test/unit/abort-action.test.ts` can drive the receipt and the
+ * wiring (same reason as `steerChild`/`stopAction`).
+ */
+export async function abortChild(
+	ctx: ChildContext,
+): Promise<AgentToolResult<unknown>> {
+	try {
+		// Only an explicit `clearQueued: false` builds an options object; the
+		// default path passes nothing, so the supervisor's own default (true)
+		// stays the single source of truth.
+		const outcome = await ctx.orchestrator.abort(
+			ctx.name,
+			ctx.params.clearQueued === false ? { clearQueued: false } : undefined,
+		);
+		return ok(abortReceipt(ctx.name, outcome));
+	} catch (error) {
+		return fail(`abort failed: ${String(error)}`, ErrorCodes.NOT_FOUND);
+	}
+}
+
+/**
+ * Wait for the child's current turn and derive its outcome from the session.
+ *
+ * Exported alongside `waitAction` for the index-layer unit tests: the claim the
+ * runtime seam takes has to be handed back when this call bails (D2), and that
+ * wiring is only observable from here.
+ */
+export async function collectChild(
 	ctx: ChildContext,
 	signal?: AbortSignal,
+	/**
+	 * #384: this node's inbox. When set, a collect that receives mail returns with
+	 * that mail instead of waiting for the child (`docs/contracts/wait-mail-preempt-v1.md`).
+	 * Absent = no query, no timer, no abort controller — today's behaviour byte for
+	 * byte (I1).
+	 */
+	mail?: MailReleaseSeam,
 ): Promise<AgentToolResult<unknown>> {
+	let stopPolling: (() => void) | undefined;
+	// #384 review round 3: same hold as `wait` — this node's postman stays off its inbox
+	// for the whole collect (entry check, interruptible seam and orchestrator fallback
+	// alike), and the `finally` below hands it back on every exit path.
+	if (mail) beginMailHold(mail.nodeId);
 	try {
 		if (signal?.aborted) return ok("interrupted (parent turn ended; children still running)");
-		const pending = signal
-			? ctx.runtime.consumeCollectInterruptible(ctx.name, signal)
-			: ctx.runtime.consumeCollect(ctx.name);
+		// #384: the inbox is checked BEFORE anything claims a result, so a preempted
+		// collect never holds a #352 claim for a result it will not deliver.
+		if (mail) {
+			const released = takePendingMail(mail.db, mail.nodeId);
+			if (released.length > 0) return mailPreemptedCollect(ctx.name, released);
+		}
+		// #312: the runtime's job table is keyed by NAME, while everything below
+		// acts on the node resolved in `ctx.found.runId`. A TRACKED job belonging to
+		// another run is a different node: consuming its snapshot here would answer
+		// with one node's result and persist it into another's run — the same silent
+		// wrong-node answer the resolver exists to stop, one layer down.
+		//
+		// Only a tracked job can be cross-checked. A released one leaves its finished
+		// cache behind (keyed by the run the snapshot CAME from, D9), and that cache is
+		// the only answer left for the node — the #320 bail wiring collects exactly
+		// that window, so an absent job must not be read as "a different run".
+		const trackedJob = ctx.runtime.get(ctx.name);
+		const foreignJob = trackedJob !== undefined && trackedJob.runId !== ctx.found.runId;
+		// #384: the mail abort and the caller's abort race into one signal — whichever
+		// lands first ends the collect, and `combined.reason` says which it was (§4).
+		// With no mail seam the combined signal is the caller's, unchanged.
+		const mailAbort = new AbortController();
+		const combined = mail
+			? (signal ? AbortSignal.any([signal, mailAbort.signal]) : mailAbort.signal)
+			: signal;
+		if (mail) stopPolling = pollInbox(mail, () => mailAbort.abort(MAIL_PREEMPT_REASON));
+		const pending = foreignJob
+			? undefined
+			: combined
+				? ctx.runtime.consumeCollectInterruptible(ctx.name, combined)
+				: ctx.runtime.consumeCollect(ctx.name);
 		if (pending) {
 			const collected = await pending;
-			if (!collected || signal?.aborted) return ok("interrupted (parent turn ended; children still running)");
-			await persistChild(ctx.store, ctx.found.runId, ctx.orchestrator, ctx.name, { preserveRetired: true });
-			return ok(renderCollect(ctx.name, collected));
+			// D2: the seam claims a terminal snapshot on the way out, because a flush in
+			// that tick would otherwise repeat it. Every bail from here hands the result
+			// to NOBODY, so the claim is handed back — a permanently suppressed notice
+			// for a result the parent never saw is the worse failure of the two. The
+			// rollback is told `claimedNow`, the flag this very call got back: only a claim
+			// THIS call took comes back (#320/1), so a result an earlier delivery already
+			// claimed keeps its evidence, and the job branch restores the notification
+			// route with it (#320/2).
+			//
+			// #384: a mail preempt is the reason the seam answered `undefined`, and it is
+			// resolved AFTER the rollback above so #352's invariant holds either way: no
+			// notice may be left claimed-but-undelivered by a preemption.
+			const callerGone = signal?.aborted === true;
+			const mailWon =
+				mail !== undefined && combined?.reason === MAIL_PREEMPT_REASON && !callerGone;
+			// #384 review P1.1: mail ended the collect, but the ledger is empty — the
+			// postman claimed the row first. Answer with what this collect DID get
+			// (`renderCollect`, the claim it took is the delivery) instead of the frozen
+			// `interrupted …`, which would blame the parent turn for something that
+			// never happened.
+			if (mailWon) {
+				const released = takePendingMail(mail.db, mail.nodeId);
+				if (released.length > 0) {
+					if (collected) {
+						// The mail wins and the child's text is dropped: hand the claim back
+						// so that round's notice can still deliver it (#352).
+						ctx.runtime.unclaimUndelivered(ctx.name, collected.snapshot, collected.claimedNow);
+					}
+					return mailPreemptedCollect(ctx.name, released);
+				}
+				if (collected) return ok(renderCollect(ctx.name, collected.snapshot));
+			}
+			if (!collected || signal?.aborted) {
+				if (collected) {
+					ctx.runtime.unclaimUndelivered(ctx.name, collected.snapshot, collected.claimedNow);
+				}
+				return ok("interrupted (parent turn ended; children still running)");
+			}
+			try {
+				await persistChild(ctx.store, ctx.found.runId, ctx.orchestrator, ctx.name, { preserveRetired: true });
+			} catch (error) {
+				// Same rule for the other bail: `renderCollect` is never reached, so the
+				// tool result will not carry this snapshot either.
+				ctx.runtime.unclaimUndelivered(ctx.name, collected.snapshot, collected.claimedNow);
+				throw error;
+			}
+			return ok(renderCollect(ctx.name, collected.snapshot));
 		}
 
 		const cached = ctx.orchestrator.cachedCollect(ctx.name);
@@ -2059,8 +3093,26 @@ async function collectChild(
 		const timeoutMs = agentDef?.timeoutMs ?? DEFAULTS.turnTimeoutMs;
 		const collected = await ctx.orchestrator.collect(ctx.name, {
 			timeoutMs,
-			...(signal ? { signal } : {}),
+			...(combined ? { signal: combined } : {}),
 		});
+		// #384: this collect may have been cut short by mail (the orchestrator answers
+		// `aborted by parent` for ANY aborted signal). Only a genuinely interrupted
+		// answer is preempted — a real result is delivered, and the mail stays pending
+		// for the postman rather than replacing it.
+		const mailWon =
+			mail !== undefined &&
+			combined?.reason === MAIL_PREEMPT_REASON &&
+			signal?.aborted !== true &&
+			collected.execution.reason === "aborted by parent";
+		if (mailWon) {
+			const released = takePendingMail(mail.db, mail.nodeId);
+			if (released.length > 0) return mailPreemptedCollect(ctx.name, released);
+			// #384 review P1.1: the mail is gone from the ledger (the postman claimed the
+			// row first), but this collect DID get a snapshot — including the child's
+			// output so far. Answering with `interrupted …` would blame the parent turn
+			// for something that never happened, so the snapshot is what goes out.
+			return ok(renderCollect(ctx.name, collected));
+		}
 		if (signal?.aborted || collected.execution.reason === "aborted by parent") {
 			return ok("interrupted (parent turn ended; children still running)");
 		}
@@ -2070,10 +3122,16 @@ async function collectChild(
 			await ctx.orchestrator.retire(ctx.name);
 			await persistChild(ctx.store, ctx.found.runId, ctx.orchestrator, ctx.name);
 		}
-		ctx.runtime.release(ctx.name);
+		// Only release a job that IS the node just collected. Releasing by name alone
+		// would drop the tracking of a still-live same-named child in another run.
+		if (!foreignJob) ctx.runtime.release(ctx.name);
 		return ok(renderCollect(ctx.name, collected));
 	} catch (error) {
 		return fail(`collect failed: ${String(error)}`, ErrorCodes.NOT_FOUND);
+	} finally {
+		// #384: never leave a 250ms timer behind a finished collect.
+		stopPolling?.();
+		if (mail) endMailHold(mail.nodeId);
 	}
 }
 
@@ -2298,11 +3356,19 @@ async function reviveChild(
 
 	try {
 		if (supervisor.isAlive(name)) {
-			await orchestrator.steer(name, params.message);
+			// #313 D5: this branch steers a live child too, so it reports the same
+			// three outcomes as `steerChild`, reusing the receipt notes rather than
+			// writing a second copy of the wording.
+			const disposition = await orchestrator.steer(name, params.message);
 			followChild(ctx, { watch: true });
-			return ok(
-				`${action === "resume" ? "Resumed" : "Continued"} ${name} (live child steered).`,
-			);
+			const prefix = `${action === "resume" ? "Resumed" : "Continued"} ${name}`;
+			if (disposition === "intercepted") {
+				return ok(`${prefix}, but the steer was ${STEER_INTERCEPTED_NOTE}.`);
+			}
+			if (disposition === "queued") {
+				return ok(`${prefix} (live child steered — ${STEER_QUEUED_NOTE}).`);
+			}
+			return ok(`${prefix} (live child steered).`);
 		}
 
 		const handle = await orchestrator.launch({
@@ -2310,6 +3376,10 @@ async function reviveChild(
 			task: params.message,
 			name,
 			...(found.child.model ? { model: found.child.model } : {}),
+			// #374 §4: a team declared its machine at FIRST launch; a resume in a
+			// later process must replay that declaration or the child falls back to
+			// the role card and its custom phase names read as `invalid_phase`.
+			...(found.child.phases ? { phases: found.child.phases } : {}),
 		});
 		// D6/D8/D5-a: spend one renewal, but only if this child was actually cut
 		// off by its turn budget.
@@ -2327,7 +3397,11 @@ async function reviveChild(
 		// and overstate how much the child achieved under the current budget.
 		const resumedChild =
 			orchestrator.childrenSnapshot().find((entry) => entry.name === handle.name) ??
-			found.child;
+			// #344 review: `found.child` may be an element of the process-wide
+			// `listRuns` snapshot, so mutating it in place would poison the cache
+			// until the next write. The fallback is latent (launch always registers
+			// the child), but a copy costs nothing and keeps the invariant local.
+			{ ...found.child };
 		// Read the verdict from `found.child`, NOT the orchestrator's record: `launch`
 		// clears `previous.execution` before returning (it is a relaunch), and
 		// `found` is a freshly parsed copy from `store.listRuns()`, so the pre-resume
@@ -2342,7 +3416,21 @@ async function reviveChild(
 			`Resumed ${handle.name} from its session. Context preserved from ${handle.sessionFile}`,
 		);
 	} catch (error) {
-		return fail(`${action} failed: ${String(error)}`, ErrorCodes.START_FAILED);
+		// #309 D4: preserve the code the launcher already decided on (e.g.
+		// `CHILD_TERMINAL` for a finished legion node) instead of flattening every
+		// failure into `START_FAILED`. A `SubagentError` carries its code by
+		// construction (`readonly code: string`), so the instance check IS the
+		// condition — testing `&& error.code` would be a branch no input can
+		// distinguish. Every other `Error` falls back to `START_FAILED`.
+		// The code rides in `details.error` only — the body text stays code-free on
+		// purpose, because the visible-text assertions in `test/unit/teams.test.ts`
+		// and `test/integration/launch-queue.test.ts` require that a code never
+		// leaks into what the model reads.
+		const code =
+			error instanceof SubagentError
+				? error.code
+				: ErrorCodes.START_FAILED;
+		return fail(`${action} failed: ${String(error)}`, code);
 	}
 }
 
@@ -2436,7 +3524,7 @@ async function launchFamily(input: {
 		// the bug's main path (a 12-step `tasks[]` fanout against `maxChildrenPerNode`).
 		launchQueue: launchQueueBounds(settings),
 		onLaunchQueueNotice: launchQueueNoticeSink(input.pi),
-		...(legion ? { legion: { db: legion.db, dbPath: legion.dbPath, nodeId: legion.nodeId, runId: run.runId, parentNodeId: legion.parentNodeId ?? undefined, parentRunId: legion.parentRunId ?? undefined, runStore: store, settings: legion.settings, eventBus: legion.eventBus } } : {}),
+		...(legion ? { legion: { db: legion.db, dbPath: legion.dbPath, nodeId: legion.nodeId, runId: run.runId, parentNodeId: legion.parentNodeId ?? undefined, parentRunId: legion.parentRunId ?? undefined, runStore: store, settings: legion.settings, eventBus: legion.eventBus, ...(legion.machineForRole ? { machineForRole: legion.machineForRole } : {}) } } : {}),
 		onBudgetRefused: input.onBudgetRefused,
 	});
 	orchestrator.restore(run);
@@ -2595,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);
@@ -2665,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
@@ -2687,6 +3778,12 @@ async function launchStep(
 				launch: session.params.worktree,
 				step: step.worktree,
 			}),
+			// #371: a phase machine is declared by the ROOT at dispatch time and is a
+			// property of the launch, not of a step — `tasks[]` fan-out carries the
+			// same declaration to every sibling (G3 then refuses any step that is not
+			// a centurion, rather than silently ignoring it).
+			...(session.params.phases !== undefined ? { phases: session.params.phases } : {}),
+			...(session.params.start !== undefined ? { start: session.params.start } : {}),
 		});
 		const recorded = session.store.findChild(session.runId, handle.name);
 		if (recorded?.nodeId && recorded.nodeId === handle.child.nodeId) {
@@ -2922,6 +4019,7 @@ type Plan =
 			steps: Array<{
 				agent: string;
 				task: string;
+				name?: string;
 				model?: string;
 				preset?: string;
 				worktree?: boolean;
@@ -2954,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\`.` };
@@ -3079,6 +4187,7 @@ async function launchUtilityFamily(input: {
 			settings: catalog.settings,
 			maxDepth: effectiveMaxDepth(catalog.settings.legion?.maxDepth),
 			eventBus: input.eventBus,
+			rootSessionFile: input.ctx.sessionManager?.getSessionFile(),
 		});
 	}
 	if (legion) input.onLegion(legion);
@@ -3139,6 +4248,7 @@ async function launchUtilityFamily(input: {
 					runStore: store,
 					settings: legion.settings,
 					eventBus: legion.eventBus,
+					...(legion.machineForRole ? { machineForRole: legion.machineForRole } : {}),
 				},
 			} : {}),
 		});
@@ -3395,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;
@@ -3444,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
@@ -3865,26 +5043,35 @@ export interface StatusChildEntry {
 	 * hold live children keep their meaning.
 	 */
 	live?: boolean;
+	/**
+	 * Tool calls in flight right now (#315, #331), innermost last. Supplied by
+	 * the supervisor; absent means no activity fact, which renders no line at all.
+	 */
+	inFlightTools?: InFlightToolStack;
 }
 
 /** Multi-child status text: one {@link renderLiveChildStatus} block per child. */
-export function renderStatusOverview(children: StatusChildEntry[]): string {
+export function renderStatusOverview(children: StatusChildEntry[], now: number = Date.now()): string {
 	const deadCount = children.filter((entry) => entry.live === false).length;
 	const liveCount = children.length - deadCount;
-	const blocks = children.map(({ child, alive, owner, pid }) =>
-		renderLiveChildStatus({
-			name: child.name,
-			state: child.state,
-			agent: child.agent,
-			kind: child.kind,
-			sessionFile: child.sessionFile,
-			execution: child.execution,
-			acceptance: child.acceptance,
-			spawnMode: child.spawnMode,
-			alive,
-			...(owner ? { owner } : {}),
-			...(pid ? { pid } : {}),
-		}),
+	const blocks = children.map(({ child, alive, owner, pid, inFlightTools }) =>
+		withInFlightToolLine(
+			renderLiveChildStatus({
+				name: child.name,
+				state: child.state,
+				agent: child.agent,
+				kind: child.kind,
+				sessionFile: child.sessionFile,
+				execution: child.execution,
+				acceptance: child.acceptance,
+				spawnMode: child.spawnMode,
+				alive,
+				...(owner ? { owner } : {}),
+				...(pid ? { pid } : {}),
+			}),
+			inFlightTools,
+			now,
+		),
 	);
 	const parts: string[] = [];
 	if (liveCount === 0) {
@@ -3943,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;
@@ -4032,16 +5219,175 @@ export function renderWait(results: WaitResult[]): string {
  */
 function ownerVerdictFor(
 	store: RunStore,
-	runs: ReturnType<RunStore["listRuns"]>,
+	runs: () => ReturnType<RunStore["listRuns"]>,
 	name: string,
 	alive: boolean,
+	runId?: string | undefined,
 ): "live" | "dead" | "unknown" | undefined {
 	if (alive) return undefined;
-	const picked = pickChildByName(runs, name);
+	// #312: a named `status` resolved ONE node, so the verdict has to come from
+	// that node's run dir. Reading it through `pickChildByName` mixed the record
+	// this call displays with the owner marker of another run's same-named node —
+	// a child whose own run dir is owned by this live process could render
+	// `owner: dead (pid gone)` and even be rewritten to `state=failed`.
+	if (runId) return ownerState(path.join(store.runDir(runId), RUN_OWNER_FILE));
+	// Only a caller with no resolved run reaches this: the registry scan happens
+	// here and nowhere earlier (#344).
+	const picked = pickChildByName(runs(), name);
 	if (!picked) return "unknown";
 	return ownerState(path.join(store.runDir(picked.run.runId), RUN_OWNER_FILE));
 }
 
+/** The run a resolved `stop` target lives in (#312). */
+export interface StopRetireScope {
+	/**
+	 * The run `stopAction` resolved this name in. The executor must read THIS
+	 * record — re-resolving the name across runs is how `stop` came to report one
+	 * node and retire another.
+	 */
+	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(", ")})` : "";
+}
+
+/**
+ * Refuse `stop({name, runId})` when that name's live job sits in another run (#312).
+ *
+ * The runtime's job table is keyed by NAME, so before this check a live child
+ * answered a call scoped to a different run and was retired anyway — the
+ * "reported one node, retired another" failure one layer above the store path.
+ * A live job is a node of exactly one run, so the two are a conflict, never a
+ * preference: neither may be retired by a tie-break. The wording is the same
+ * elsewhere/ambiguity pair the store path uses, because the caller's lever is
+ * the same — name the run that actually holds the node.
+ */
+function stopScopeMismatchMessage(
+	name: string,
+	live: { runId: string; nodeId?: string | undefined; state: string },
+	runs: ReturnType<RunStore["listRuns"]>,
+): string {
+	// The scan names every same-named node; the live job is added on its own
+	// because a just-spawned child may not have a persisted record yet.
+	const scanned = scopeHitFor({ name, directRunId: undefined, explicitRunId: undefined, runs });
+	const candidates = dedupeChildScopeCandidates([
+		...(scanned.kind === "elsewhere" ? scanned.candidates : []),
+		{
+			runId: live.runId,
+			...(live.nodeId ? { nodeId: live.nodeId } : {}),
+			state: live.state,
+		},
+	]);
+	return candidates.length > 1
+		? ambiguousChildMessage("stop", name, candidates)
+		: notDirectChildMessage("stop", name, candidates);
+}
+
+/**
+ * One entry per node: the same run can be seen twice (persisted scan + live job).
+ *
+ * Sorted by `runId` like the resolver's own scan, so the message is stable.
+ */
+function dedupeChildScopeCandidates(
+	candidates: readonly ChildScopeCandidate[],
+): ChildScopeCandidate[] {
+	const seen = new Set<string>();
+	const out: ChildScopeCandidate[] = [];
+	for (const candidate of candidates) {
+		const key = `${candidate.runId}\u0000${candidate.nodeId ?? ""}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		out.push(candidate);
+	}
+	return out.sort((a, b) => a.runId.localeCompare(b.runId));
+}
+
 /**
  * Retire a named child or every child tracked by this session.
  * `force: true` → hard path (graceful:false / SIGTERM→SIGKILL); omit/false → graceful.
@@ -4054,7 +5400,22 @@ export async function stopAction(input: {
 	 * (foreign/restarted runs). Omitted callers keep the runtime-only scope.
 	 */
 	store?: RunStore;
-	retire: (name: string, opts?: RetireOptions) => Promise<void>;
+	/**
+	 * #312: the run this call is scoped to (`runId` on the tool call, else the
+	 * session's own run). Only a child of THIS run may be stopped by name; a
+	 * same-named record elsewhere is reported instead of adopted.
+	 */
+	runId?: string | undefined;
+	/** The run this session owns, used when the call names no `runId` (#312). */
+	sessionRunId?: string | undefined;
+	/**
+	 * Retire one already-resolved target.
+	 *
+	 * `scope` carries the run the target was resolved IN, so the executor can act
+	 * on that exact record instead of resolving the name again by preference
+	 * (#312) — one resolver here, one node retired there.
+	 */
+	retire: (name: string, opts?: RetireOptions, scope?: StopRetireScope) => Promise<void>;
 }): Promise<AgentToolResult<unknown>> {
 	const { params, runtime, retire } = input;
 	if (params.name && params.all) {
@@ -4067,41 +5428,107 @@ export async function stopAction(input: {
 	const retireOpts: RetireOptions | undefined = force ? { graceful: false } : undefined;
 	const jobs = runtime.activeJobs();
 	const active = jobs.filter((job) => job.state !== "retired");
-	let targets: string[];
+	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) => job.name);
+		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;
 		const target = name ? jobs.find((job) => job.name === name) : undefined;
+		if (name && input.runId !== undefined && target && target.runId !== input.runId) {
+			// #312: the job table is keyed by NAME, so a live child answered a call
+			// scoped to another run and got retired anyway — the presented node and the
+			// retired node disagreed again, one layer up (fixing only the store path
+			// would have left this silent). A live job belongs to exactly one run, so
+			// the mismatch is a conflict: refuse it with the wording the store path uses.
+			return fail(
+				stopScopeMismatchMessage(name, target, input.store ? input.store.listRuns() : []),
+				ErrorCodes.NOT_FOUND,
+			);
+		}
 		if (!target) {
-			// 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;
+			// Not tracked by this session, but a foreign/restarted run may still own a
+			// persisted record — the same records `status` can display.
+			//
+			// #312: it has to be this session's OWN child. The old fallback took
+			// whatever `pickChildByName` preferred across every run, and when that
+			// happened to be a different run's retired record the whole call collapsed
+			// into `No non-retired children to stop.` — which told the caller nothing
+			// about the name being ambiguous, and hid the node it was trying to stop.
+			const runs = input.store ? input.store.listRuns() : [];
+			const directRunId = scopeRunIdFor({
+				runId: input.runId,
+				sessionRunId: input.sessionRunId,
+				trackedRunId: name ? runtime.get(name)?.runId : undefined,
+			});
+			const found = name ? foundInScope(runs, directRunId, name) : null;
 			if (!found) {
-				return fail(`unknown child: ${params.name} (not tracked by this session).`, ErrorCodes.NOT_FOUND);
+				const hit = name
+					? scopeHitFor({ name, directRunId, explicitRunId: input.runId, runs })
+					: undefined;
+				if (hit?.kind === "elsewhere") {
+					const ambiguous = hit.candidates.length > 1;
+					// A session with no run of its own (#209-3: a foreign or restarted run's
+					// record) has no direct children, so a unique match stays reachable. With
+					// a scope, a name that is not in it is refused instead of adopted — that
+					// adoption is what turned into `No non-retired children to stop.`
+					if (ambiguous || directRunId !== undefined) {
+						const message = ambiguous
+							? ambiguousChildMessage("stop", name ?? "", hit.candidates)
+							: notDirectChildMessage("stop", name ?? "", hit.candidates);
+						return fail(message, ErrorCodes.NOT_FOUND);
+					}
+					const permissive = name ? foundElsewhere(runs, name, hit) : null;
+					if (!permissive) {
+						return fail(`unknown child: ${params.name} (not tracked by this session).`, ErrorCodes.NOT_FOUND);
+					}
+					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 {
+				const resolved = stopResolutionFromRecord(found.child, found.runId);
+				targets = resolved.targets;
+				alreadyRetired = resolved.note;
 			}
-			targets = found.child.state === "retired" ? [] : [found.child.name];
 		} else {
-			targets = target.state === "retired" ? [] : [target.name];
+			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);
+	for (const { name } of targets) runtime.cancelWatch(name);
 
 	const stopped: string[] = [];
+	const reaped: string[] = [];
 	const failures: string[] = [];
-	for (const name 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. The retire adapter can then resolve its persisted run record.
-			await retire(name, retireOpts);
+			// 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.
@@ -4110,14 +5537,243 @@ 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);
 }
 
+/**
+ * #352: one completion claim a `wait` took for a result the parent never saw.
+ *
+ * `waitAction` claims a settled child's result on its finished-cache probe
+ * (`runtime.consumeCollect`, `index.ts` — the probe is NOT side-effect free since
+ * notice-claim-v1), and the tool layer in this file can still throw the rendered
+ * result away when the parent turn ends. Only a claim THIS call took travels here
+ * (`claimedNow === true`): a key an earlier real delivery claimed is evidence, not
+ * something a bail may spend (#320/1).
+ */
+export interface WaitClaim {
+	name: string;
+	snapshot: CollectSnapshot;
+}
+
+/**
+ * #352: hand back every claim a discarded `wait` result owed.
+ *
+ * `unclaimUndelivered`, never `unclaimReported`: nothing reached the parent, so the
+ * queued notice is the ONLY remaining route — the rollback gives the claim back and
+ * drops no copy (D2/D7). `claimedNow` is always `true` here: `WaitClaim`s only exist
+ * for claims this call took.
+ *
+ * #352 review (major 1): the claim arrives ASYNCHRONOUSLY. `waitAction`'s
+ * finished-cache probe is a promise (`consumeCollect` → `ensureCollect`), and the wait
+ * can bail long before it answers — `signal?.aborted`, `WAIT_INTERRUPTED` and
+ * `WaitTimeoutError` all win their race inside `waitOne` while that collect is still in
+ * flight. The probe then resolves to a terminal snapshot and claims `(runId, name,
+ * round)` AFTER the details object was already built, so the bail has to wait for that
+ * answer before it rolls anything back: `details.waitClaims` is a live array (shared by
+ * reference with `waitAction`), and `details.waitClaimsPending` is the promise that
+ * resolves once the probe has folded its claim in. Awaited first, both windows are
+ * covered: the claim that was already there, and the one that landed late.
+ *
+ * The await is bounded by the probe's own collect, which is what makes the claim
+ * knowable at all; returning now and rolling back from a detached continuation would
+ * hand the claim back after the frozen `interrupted …` line already went out.
+ */
+export async function releaseWaitClaims(runtime: SessionRuntime, details: unknown): Promise<void> {
+	if (details === null || typeof details !== "object") return;
+	const record = details as { waitClaims?: unknown; waitClaimsPending?: unknown };
+	const pending = record.waitClaimsPending;
+	if (pending !== undefined) {
+		try {
+			await (pending as Promise<unknown>);
+		} catch {
+			// A throwing probe took no claim — nothing to give back.
+		}
+	}
+	const claims = record.waitClaims;
+	if (!Array.isArray(claims)) return;
+	for (const claim of claims as WaitClaim[]) {
+		runtime.unclaimUndelivered(claim.name, claim.snapshot, true);
+	}
+}
+
+/**
+ * What a control call answers when the caller's abort lands after it returned
+ * (#352 + #384 review P0-3).
+ *
+ * #352: the frozen head line REPLACES the rendered result, so the parent never sees
+ * it — and `wait` CLAIMS a settled child's completion on its finished-cache probe.
+ * The result is thrown away here, so the claim has to go back (exactly what
+ * `collectChild` owes on its own bails): a claim nobody delivered suppresses that
+ * round's notice forever.
+ *
+ * #384 review P0-3: a MAIL result is thrown away the same way, but a claim is not
+ * the only thing it held — the mails inside it were already `PENDING → ACCEPTED`, and
+ * `takePendingMail` has no way back. Left alone, the text would be lost for good
+ * (before #384 the message was still `PENDING` and a restart would have delivered
+ * it). So the discarded result's mail is re-enqueued as fresh `PENDING` rows
+ * (`Redelivered: ` subject, same sender/recipient/body) and the postman's next tick
+ * delivers it like any other mail.
+ */
+export async function interruptedControlResult(input: {
+	result: AgentToolResult<unknown>;
+	runtime: SessionRuntime;
+	legion?: OrchestratorLegionContext;
+}): Promise<AgentToolResult<unknown>> {
+	await releaseWaitClaims(input.runtime, input.result.details);
+	redeliverPreemptedMail(input.legion, input.result.details);
+	return ok("interrupted (parent turn ended; children still running)");
+}
+
+/** Re-enqueue the mail a discarded (`state: "mail"`) result was carrying. */
+function redeliverPreemptedMail(
+	legion: OrchestratorLegionContext | undefined,
+	details: unknown,
+): void {
+	if (!legion || details === null || typeof details !== "object") return;
+	const record = details as { state?: unknown; mailIds?: unknown };
+	if (record.state !== "mail" || !Array.isArray(record.mailIds)) return;
+	const ids = record.mailIds.filter((id): id is number => Number.isSafeInteger(id));
+	if (ids.length === 0) return;
+	try {
+		redeliverMail(legion.db, ids);
+	} catch {
+		// The ledger refused the copy (closed DB, a racing shutdown). Nothing further to
+		// promise: the frozen line is still the answer, and swallowing beats failing a
+		// bail that has already been decided.
+	}
+}
+
+/**
+ * #384: the abort reason that says "this node's inbox got mail", as opposed to
+ * "the caller left". `AbortSignal.any` forwards the reason of whichever source
+ * aborted FIRST (contract §4), so the combined signal's `reason` is the verdict on
+ * who won the race — no bookkeeping flag to fall out of sync.
+ */
+const MAIL_PREEMPT_REASON = Symbol("legion mail preempted the blocking call");
+
+/**
+ * Mount the #352 claim record on a wait result's `details` (both fields, always).
+ *
+ * #352 review (major 1): mount BOTH unconditionally. Deciding on `claims.length` was
+ * a no-op: one probe means at most one claim, and the probe has usually not answered
+ * yet at this point — so the length test mounted nothing in the window that matters,
+ * and when it did mount it shared a reference with a caller that could reach it anyway.
+ * The array stays live (late pushes land in the same object) and the promise says
+ * when the probe got its answer.
+ */
+function withWaitClaims(
+	details: Record<string, unknown>,
+	claims: WaitClaim[],
+	pending?: Promise<WaitClaim[]>,
+): Record<string, unknown> {
+	details.waitClaims = claims;
+	if (pending) {
+		// Non-enumerable: this is a live promise, and `details` is the tool result's
+		// record — a promise has no business in a serialized transcript.
+		Object.defineProperty(details, "waitClaimsPending", {
+			value: pending,
+			enumerable: false,
+			configurable: true,
+		});
+	}
+	return details;
+}
+
+/**
+ * Contract §2: the mail that ended the blocking call, as a NORMAL tool result.
+ *
+ * Not an error and not `interrupted …` — the model reads the mail and carries on.
+ * The `details` shape is the one the contract froze: `state`, `mailIds`, `targets`,
+ * plus the wait's claim record when the caller has one (a `collect` takes no claim).
+ *
+ * `sections` are the parts of the blocking call that DID happen, in order: the mail
+ * itself first (that is what ended the call), then whatever the call had already
+ * delivered, then the frozen status line.
+ */
+function mailPreemptedResult(input: {
+	released: readonly LegionMessage[];
+	targets: readonly string[];
+	sections: readonly string[];
+	claims?: WaitClaim[];
+	pending?: Promise<WaitClaim[]>;
+}): AgentToolResult<unknown> {
+	return {
+		content: [
+			{
+				type: "text",
+				text: [renderReleasedMail(input.released), ...input.sections].join("\n\n"),
+			},
+		],
+		details: withWaitClaims(
+			{
+				state: "mail",
+				mailIds: input.released.map((message) => message.id),
+				targets: [...input.targets],
+			},
+			input.claims ?? [],
+			input.pending,
+		),
+	};
+}
+
+/**
+ * `wait`: the mail, the results this wait already collected, and — once — who is
+ * still running (#384 review P0-2).
+ *
+ * Review finding: the earlier shape reused `renderWait`'s body, which labels an
+ * aborted result `interrupted (parent turn ended; children still running)` — a
+ * conclusion about the PARENT that is false here: the wait ended because mail
+ * arrived, and the parent turn is alive, reading that mail. So the interrupted
+ * lines are dropped, every result the wait DID get is kept verbatim, and the
+ * still-running fact is stated once, plainly.
+ */
+function mailPreemptedWait(input: {
+	released: readonly LegionMessage[];
+	names: readonly string[];
+	/** Results that carried a snapshot — they were delivered, so they stay. */
+	delivered: readonly WaitResult[];
+	/** Names this wait had not finished when the mail landed. */
+	running: readonly string[];
+	claims: WaitClaim[];
+	pending?: Promise<WaitClaim[]>;
+}): AgentToolResult<unknown> {
+	const sections = input.delivered.map((result) => renderCollect(result.name, result.snapshot!));
+	if (input.running.length > 0) sections.push(`Still running: ${input.running.join(", ")}`);
+	return mailPreemptedResult({
+		released: input.released,
+		targets: input.names,
+		sections,
+		claims: input.claims,
+		...(input.pending ? { pending: input.pending } : {}),
+	});
+}
+
+/** `collect`: the mail plus the frozen "collect again" instruction (contract §2). */
+function mailPreemptedCollect(
+	name: string,
+	released: readonly LegionMessage[],
+): AgentToolResult<unknown> {
+	return mailPreemptedResult({
+		released,
+		targets: [name],
+		sections: [
+			"The collect was interrupted by this mail; call collect again after handling it.",
+		],
+	});
+}
+
 export async function waitAction(input: {
 	params: SubagentParams;
 	signal?: AbortSignal;
@@ -4126,20 +5782,72 @@ export async function waitAction(input: {
 	allAgents?: AgentConfig[];
 	store: RunStore;
 	cwd: string;
+	/**
+	 * #384: this node's inbox, when the caller is a legion node. A wait that receives
+	 * mail returns AT ONCE with that mail instead of waiting out its timeout
+	 * (`docs/contracts/wait-mail-preempt-v1.md`). Absent = no query, no timer, no
+	 * abort controller — today's behaviour byte for byte (I1).
+	 */
+	mail?: MailReleaseSeam;
 }): Promise<AgentToolResult<unknown>> {
 	const { params, signal, runtime, agents, allAgents = agents, store, cwd } = input;
 	const jobs = runtime.activeJobs();
+	// #352: every claim THIS call takes. The array is shared by REFERENCE with the
+	// returned `details.waitClaims`, because the probe below answers asynchronously:
+	// a claim that lands after the details object was built must still be visible to
+	// a caller that discards the rendered result.
+	const claims: WaitClaim[] = [];
+	// #352 review (major 1): the probe's answer, absent when this wait has no probe at
+	// all (live targets). It resolves to `claims` once the probe's own claim — if any —
+	// has been folded in, and travels out as `details.waitClaimsPending` so a bail that
+	// lands while it is still in flight can wait for it instead of rolling back nothing.
+	let claimsPending: Promise<WaitClaim[]> | undefined;
 	let targets = resolveWaitTargets(
 		{ name: params.name, all: params.all },
 		jobs,
 	);
+	const mail = input.mail;
+	// #384: look in the inbox ONCE here — before the finished-cache probe below can
+	// take a #352 claim, so the preempted path is provably claim-free. `signal?.aborted`
+	// at entry means the caller is already gone: I5 keeps that path exactly as it was,
+	// mail or no mail.
+	//
+	// Review P1.2: only a wait that HAS somewhere to wait is preempted. `unknown child`
+	// and the parameter/liveness errors keep precedence — mail is not an answer to a
+	// question this call did not ask, and hiding the error made the miss look like a
+	// successful call whose result was mail.
+	if (targets.ok && mail && signal?.aborted !== true) {
+		const released = takePendingMail(mail.db, mail.nodeId);
+		if (released.length > 0) {
+			return mailPreemptedWait({
+				released,
+				names: targets.names,
+				delivered: [],
+				running: targets.names,
+				claims,
+			});
+		}
+	}
 	if (!targets.ok) {
 		// A name that is merely finished (not live) is still waitable via the
-		// runtime's finished cache — probe it with consumeCollect, which is
-		// side-effect free for a job that is not in the live set.
+		// runtime's finished cache — probe it with consumeCollect. NOTE: since
+		// notice-claim-v1 that probe is NOT side-effect free: a cache hit claims the
+		// result, which is correct here — the wait below returns the same result to the
+		// parent, so the pushed notice for it is suppressed instead of duplicating it.
+		// It is also why the claim travels back out (#352): if the caller never hands
+		// the result over, nobody else can, and the claim must be given back.
 		if (params.name && !params.all) {
-			const cached = runtime.consumeCollect(params.name);
-			if (cached) {
+			const probe = runtime.consumeCollect(params.name);
+			if (probe) {
+				const name = params.name;
+				claimsPending = probe.then((claimed: ClaimedCollect) => {
+					// #320/1: only a claim THIS call took may come back later.
+					if (claimed.claimedNow) claims.push({ name, snapshot: claimed.snapshot });
+					return claims;
+				}, () => {
+					// A throwing collect is the `wait` below's problem, not the probe's.
+					return claims;
+				});
 				targets = { ok: true, names: [params.name] };
 			} else {
 				return unknownChild(params.name, store, cwd);
@@ -4162,12 +5870,77 @@ export async function waitAction(input: {
 				);
 			}),
 		);
-	const results = await runtime.wait(targets.names, { timeoutMs, ...(signal ? { signal } : {}) });
+	// #384: the mail abort and the caller's abort race into one signal, so whichever
+	// lands FIRST ends the wait — and `reason` says which one it was (contract §4).
+	// With no mail seam the combined signal is the caller's, unchanged.
+	const mailAbort = new AbortController();
+	const combined = mail
+		? (signal ? AbortSignal.any([signal, mailAbort.signal]) : mailAbort.signal)
+		: signal;
+	let stopPolling: (() => void) | undefined;
+	if (mail) stopPolling = pollInbox(mail, () => mailAbort.abort(MAIL_PREEMPT_REASON));
+	// #384 review round 3: while this call is blocked, this node's own postman must NOT
+	// deliver — otherwise the mail is `ACCEPTED` and queued behind the host's followUp
+	// long before the first poll tick, and the wait sees an empty inbox for its whole
+	// timeout (the production hole the review found). Held across the ONE blocking
+	// region and released in `finally`, so a timeout, an abort and a throw all give the
+	// inbox back. Taking the mail below happens after that release, with no `await` in
+	// between, so nothing can slip into the gap.
+	if (mail) beginMailHold(mail.nodeId);
+	let results: WaitResult[];
+	try {
+		results = await runtime.wait(targets.names, {
+			timeoutMs,
+			...(combined ? { signal: combined } : {}),
+		});
+	} finally {
+		// #384: never leave a 250ms timer behind a finished wait.
+		stopPolling?.();
+		if (mail) endMailHold(mail.nodeId);
+	}
+	// #384 review P0-2: mail preempts this wait UNCONDITIONALLY — no "did anything get
+	// delivered" test, no "did the probe run" test. Those two extra conditions were an
+	// invention: they made a wait that received mail answer as if the wait had simply
+	// timed out, with `interrupted (parent turn ended…)` naming a turn that never
+	// ended. What the wait DID collect rides along in the body instead (delivered
+	// results verbatim), and `details.waitClaims` is still mounted, so a claim this
+	// call took is never dropped on the floor.
+	//
+	// Whoever aborted FIRST still wins (contract §4): a caller abort keeps the frozen
+	// `interrupted …` rendering even when mail landed a tick later (I5).
+	if (
+		mail &&
+		combined?.reason === MAIL_PREEMPT_REASON &&
+		signal?.aborted !== true
+	) {
+		const released = takePendingMail(mail.db, mail.nodeId);
+		// Empty = the postman took it during the abort. Nothing to hand over, so fall
+		// through to the ordinary render rather than inventing a result.
+		if (released.length > 0) {
+			return mailPreemptedWait({
+				released,
+				names: targets.names,
+				delivered: results.filter((result) => result.snapshot !== undefined),
+				running: results
+					.filter((result) => result.snapshot === undefined)
+					.filter((result) => result.interrupted === true || result.stillRunning === true)
+					.map((result) => result.name),
+				claims,
+				...(claimsPending ? { pending: claimsPending } : {}),
+			});
+		}
+	}
 	const text = renderWait(results);
-	const details = buildWaitTimeoutDetails(results);
-	return details
-		? { content: [{ type: "text", text }], details }
-		: ok(text);
+	const timeoutDetails = buildWaitTimeoutDetails(results);
+	// #352: `details.waitClaims` is the only record of what this call took — the tool
+	// layer's abort net replaces the rendered result with the frozen `interrupted …`
+	// line, and without this the claim it leaves behind suppresses that round's notice
+	// forever (see `withWaitClaims`).
+	const details: Record<string, unknown> = timeoutDetails ? { ...timeoutDetails } : {};
+	return {
+		content: [{ type: "text", text }],
+		details: withWaitClaims(details, claims, claimsPending),
+	};
 }
 
 export function renderAgentList(