pi-legion 3.1.0 → 4.0.0

package/src/extension/legion-commands.ts

@@ -48,9 +48,9 @@ import {
 import type { StatusVizSnapshot } from "../tui/status.ts";
 import { createLegionViewFactory } from "../tui/viz/view.ts";
 import {
-	parseSessionMessages,
 	type ChatItemSettings,
 } from "../tui/chat-items.ts";
+import { readSessionMessagesFile } from "../tui/session-messages-file.ts";
 import {
 	createTreeViewFactory,
 	type TreeNodeSnapshot,
@@ -96,8 +96,8 @@ export interface LegionCommandDeps {
 	bus: LegionEventBus;
 	runtime: LegionCommandRuntime;
 	supervisor: RpcEventSource;
-	/** Graceful retire via the subagent `stop` action (see legion-stop.ts). */
-	stop?: (params: { name?: string; all?: boolean }) => Promise<{ ok: boolean; text: string }>;
+	/** Retire via the subagent `stop` action (see legion-stop.ts); pass `force: true` for hard retire. */
+	stop?: (params: { name?: string; all?: boolean; force?: boolean }) => Promise<{ ok: boolean; text: string }>;
 	/**
 	 * Persisted child snapshot used by `subagent({ action: "status" })`.
 	 * Undefined when this process has no run-store record for `name`.
@@ -255,13 +255,13 @@ function readSessionBackfill(
 	sessionFile: string,
 	_maxBackfillTurns: number,
 ): LiveOverlayBackfillResult | undefined {
-	// Take the size before parsing: if the append-only file grows during the
-	// parse, the next poll sees that newer size and can safely re-read it.
-	const fileSize = readSessionSize(sessionFile);
-	if (fileSize === undefined) return undefined;
+	// Incremental reader (#234): cold cache reads from byte 0 once; later polls
+	// seek past the fingerprint offset. Take size via the reader so a concurrent
+	// append is visible on the next tick.
 	try {
-		const messages = parseSessionMessages(readFileSync(sessionFile, "utf8"));
-		return { messages, cursor: sessionCursor(messages, fileSize) };
+		const loaded = readSessionMessagesFile(sessionFile);
+		if (!loaded) return undefined;
+		return { messages: loaded.messages, cursor: sessionCursor(loaded.messages, loaded.fileSize) };
 	} catch {
 		return undefined;
 	}
@@ -271,27 +271,29 @@ function readSessionDelta(
 	sessionFile: string,
 	cursor: LiveOverlayBackfillCursor,
 ): LiveOverlayBackfillResult | undefined {
-	// The append-only JSONL file is only reparsed after its byte size changes.
+	// Size gate first: unchanged append-only file ⇒ no open/parse (#234).
 	const fileSize = readSessionSize(sessionFile);
 	if (fileSize === undefined || fileSize === cursor.fileSize) return undefined;
-	let messages: ReturnType<typeof parseSessionMessages>;
+	let loaded: ReturnType<typeof readSessionMessagesFile>;
 	try {
-		messages = parseSessionMessages(readFileSync(sessionFile, "utf8"));
+		loaded = readSessionMessagesFile(sessionFile);
 	} catch {
 		return undefined;
 	}
-	const nextCursor = sessionCursor(messages, fileSize);
+	if (!loaded) return undefined;
+	const messages = loaded.messages;
+	const nextCursor = sessionCursor(messages, loaded.fileSize);
 	if (
 		nextCursor.messageCount < cursor.messageCount ||
 		nextCursor.turnCount < cursor.turnCount ||
 		nextCursor.assistantMessageCount < cursor.assistantMessageCount ||
-		fileSize < cursor.fileSize
+		loaded.fileSize < cursor.fileSize
 	) {
 		// Do not move a monotonic cursor backwards during a concurrent partial write.
 		return undefined;
 	}
-	// Return the full parsed transcript; the viewer compares the message cursor
-	// and appends only new entries. This covers assistant appends within a turn.
+	// Return the accumulated transcript; the viewer slices by message cursor.
+	// Hot path only parsed bytes past the shared session.ts fingerprint offset.
 	return { messages, cursor: nextCursor };
 }
 
@@ -357,7 +359,18 @@ function treeForLiveSource(
 				deps.bus.on(type, (event) => {
 					if (event.nodeId !== nodeId) return;
 					if (event.id === undefined && !processEventTypes.has(event.type)) return;
-					refresh();
+					// #261: `text_delta` is one streamed token. The token carries no tree state, so
+					// the snapshot below would only re-read what it already has — and
+					// `deps.runtime.treeNodes()` is a synchronous SQLite subtree scan (~0.95–1.09 ms
+					// p50 at 120 nodes), once per token for the whole life of the modal. Usage rows
+					// land via other paths, so a skipped snapshot defers their pickup to the next
+					// non-delta event (the backfill poll keeps the transcript current). Same
+					// exclusion the /legion tree view's subscription in this file and the status
+					// board in runtime.ts already apply.
+					//
+					// The listener below still fires: this event's only job here is the transcript,
+					// so do not re-add a refresh on the `text_delta` branch.
+					if (event.type !== "text_delta") refresh();
 					listener({
 						...(event.id === undefined ? {} : { id: event.id }),
 						domain: event.id === undefined ? "process" : "stored",
@@ -431,6 +444,17 @@ function openLiveOverlay(
 	nodeId: string,
 	onStop?: (nodeId: string) => void,
 ): void {
+	// #261/H1: every caller path funnels here (the view's `o`, the classic tree's
+	// `o`, a mouse click, `/legion <node>`, the status widget). Opening the same
+	// node twice used to mount a second host overlay while the first stayed
+	// pending: `controller.open()` closes the previous session but cannot resolve
+	// the previous `ui.custom()` promise, whose `done` is passed by pi into the
+	// factory. The orphaned `/legion` command promise never settled, and pi queues
+	// every later prompt behind it — the modal was there but frozen. Guarding the
+	// already-open node keeps that promise alive so closing it resolves normally.
+	// `controller.getCurrent()` is set synchronously by `open()`, so this also
+	// catches a double-open arriving in the same stdin chunk.
+	if (controller.getCurrent()?.nodeId === nodeId) return;
 	// #193: the overlay must cover the floating frame only. A full-screen overlay
 	// would make pi-tui discard every host cell (its composite has no transparency
 	// option), so the area around the frame collapsed to the terminal's default

package/src/extension/legion-doctor.ts

@@ -80,7 +80,7 @@ export const LEGION_SLASH_HELP_LINES = [
 	"/legion summary [--all] [<name>]",
 	"/legion timing [--json] [<name>] — wall / generation / other timing for children",
 	"/legion doctor [section]",
-	"/legion stop [name|all]",
+	"/legion stop [--force|-f] [name|all]",
 	"/legion --tree | /legion <node>",
 	"/legion help",
 ] as const;

package/src/extension/legion-stop.ts

@@ -3,6 +3,8 @@
  *   - `/legion stop` (all) / `/legion stop <name>` — thin wrapper over the
  *     subagent tool's `stop` action (graceful retire; a retired parent's own
  *     session shutdown retires its subtree, so stopping a parent cascades).
+ *   - `/legion stop --force` / `-f` — same targets with `force: true` (hard
+ *     retire; see #179 / StopDeps.force).
  *   - `x` on the selected agent in the /legion view → confirm → stop it.
  * Esc no longer stops children (esc-no-retire-v3); only `/legion stop` or
  * process exit retires. Everything here is pure/injectable for unit tests.
@@ -49,6 +51,18 @@ function jobForNode(node: StopNode, live: readonly StopJob[]): StopJob | undefin
 	return live.find((job) => job.nodeId === node.id) ?? (node.depth <= 1 ? live.find((job) => !job.nodeId && job.name === node.name) : undefined);
 }
 
+/** Strip `--force` / `-f` from `/legion stop` args; remainder is the name|all query. */
+export function parseStopArg(arg: string): { query: string; force: boolean } {
+	const tokens = arg.trim().split(/\s+/).filter(Boolean);
+	let force = false;
+	const rest: string[] = [];
+	for (const token of tokens) {
+		if (token === "--force" || token === "-f") force = true;
+		else rest.push(token);
+	}
+	return { query: rest.join(" "), force };
+}
+
 export function resolveStopTarget(arg: string, jobs: readonly StopJob[], nodes: readonly StopNode[]): StopTarget {
 	const query = arg.trim();
 	if (query === "" || query === "all") return { kind: "all" };
@@ -69,21 +83,32 @@ export function resolveStopTarget(arg: string, jobs: readonly StopJob[], nodes:
 	return { kind: "notFound", query };
 }
 
-/** Completions for `/legion stop <prefix>`: `all`, live child names, then nested live agents as parent/name. */
+/** Completions for `/legion stop <prefix>`: optional `--force`, `all`, live names, nested parent/name. */
 export function stopCompletions(prefix: string, jobs: readonly StopJob[], nodes: readonly StopNode[]): Array<{ value: string; label: string }> {
+	const { query, force } = parseStopArg(prefix);
+	const flagPrefix = force ? "--force " : "";
 	const live = liveJobs(jobs);
 	const byId = new Map(nodes.map((node) => [node.id, node]));
-	const out: Array<{ value: string; label: string }> = [{ value: "all", label: `all (${live.length} live)` }];
-	for (const job of live) out.push({ value: job.name, label: job.name });
+	const out: Array<{ value: string; label: string }> = [{ value: `${flagPrefix}all`, label: `all (${live.length} live)` }];
+	for (const job of live) out.push({ value: `${flagPrefix}${job.name}`, label: job.name });
 	const seen = new Set(out.map((item) => item.value));
 	for (const node of nodes) {
 		if (node.depth <= 1 || !isLiveNode(node)) continue;
 		const label = nodeLabel(node, byId);
-		if (seen.has(label)) continue;
-		seen.add(label);
-		out.push({ value: label, label: `${label} (nested)` });
+		const value = `${flagPrefix}${label}`;
+		if (seen.has(value)) continue;
+		seen.add(value);
+		out.push({ value, label: `${label} (nested)` });
 	}
-	return out.filter((item) => item.value.startsWith(prefix));
+	const trimmed = prefix.trim();
+	const offerForce =
+		!force && (trimmed === "" || "--force".startsWith(trimmed) || trimmed === "-f" || (trimmed.startsWith("-") && "-f".startsWith(trimmed)));
+	const names = out.filter((item) => {
+		const bare = force ? item.value.slice(flagPrefix.length) : item.value;
+		return bare.startsWith(query);
+	});
+	if (offerForce) names.unshift({ value: "--force", label: "--force (hard retire)" });
+	return names;
 }
 
 export interface StopDeps {
@@ -91,16 +116,16 @@ export interface StopDeps {
 	nodes(): readonly StopNode[];
 	/**
 	 * Retire via the subagent `stop` action; resolves to its summary text.
-	 * Nova follow-up (#179): `/legion stop --force` may pass `force: true`
-	 * (hard retire). Default remains graceful.
+	 * `/legion stop --force` passes `force: true` (hard retire). Default remains graceful.
 	 */
 	stop(params: { name?: string; all?: boolean; force?: boolean }): Promise<{ ok: boolean; text: string }>;
 	notify(message: string, type: "info" | "warning" | "error"): void;
 }
 
-/** `/legion stop [name|all]`. Returns the notified message (for tests). */
+/** `/legion stop [--force|-f] [name|all]`. Returns the notified message (for tests). */
 export async function runLegionStop(arg: string, deps: StopDeps): Promise<string> {
-	const target = resolveStopTarget(arg, deps.jobs(), deps.nodes());
+	const { query, force } = parseStopArg(arg);
+	const target = resolveStopTarget(query, deps.jobs(), deps.nodes());
 	const say = (message: string, type: "info" | "warning" | "error" = "info"): string => {
 		deps.notify(message, type);
 		return message;
@@ -113,10 +138,11 @@ export async function runLegionStop(arg: string, deps: StopDeps): Promise<string
 		return say(`${target.label} is owned by ${target.owner}; stop ${target.owner} to retire it with its subtree (/legion stop ${target.owner}).`, "warning");
 	}
 	if (target.kind === "all" && liveJobs(deps.jobs()).length === 0) return say("Nothing running: no live subagents.");
-	const result = await deps.stop(target.kind === "all" ? { all: true } : { name: target.name });
+	const base = target.kind === "all" ? { all: true as const } : { name: target.name };
+	const result = await deps.stop(force ? { ...base, force: true } : base);
 	return say(result.text, result.ok ? "info" : "error");
 }
 
 /** Dim hint shown in the status strip while children are live (aboveEditor / tree). */
-export const IDLE_STOP_HINT = "/legion stop [name|all]";
+export const IDLE_STOP_HINT = "/legion stop [--force] [name|all]";
 export const IDLE_STOP_HINT_SHORT = "/legion stop";

package/src/extension/legion-tools.ts

@@ -11,7 +11,7 @@ import { Type } from "typebox";
 import type { LegionSettings } from "../shared/types.ts";
 import { extractVerdict, parseSessionFile } from "../shared/session.ts";
 import type { LegionSupervisor } from "../supervisor/types.ts";
-import { sqliteHasRow, type DatabaseSync } from "../legion/db.ts";
+import { sqliteHasRow, withTransaction, type DatabaseSync } from "../legion/db.ts";
 import type { LegionEventBus } from "./event-bus.ts";
 import { appendEvent } from "../legion/events.ts";
 import {
@@ -137,9 +137,13 @@ export class LegionPostman {
 	}
 
 	private refreshHeartbeats(children: readonly LegionNode[]): void {
-		for (const child of children) {
-			if (this.supervisor.isAlive(child.name)) heartbeatNode(this.db, child.id, this.now);
-		}
+		const alive = children.filter((child) => this.supervisor.isAlive(child.name));
+		if (alive.length === 0) return;
+		// One transaction for the whole tick: avoids per-child implicit
+		// autocommit fsync under PRAGMA synchronous=FULL (#236 P1).
+		withTransaction(this.db, () => {
+			for (const child of alive) heartbeatNode(this.db, child.id, this.now);
+		});
 	}
 
 	private async deliverChildren(children: readonly LegionNode[]): Promise<void> {
@@ -244,6 +248,19 @@ export class LegionPostman {
 			const firstRootChild = this.firstRootChild(node);
 			if (firstRootChild && this.supervisor.isAlive(firstRootChild.name)) continue;
 			if (wasOrphanReportedRecently(this.db, node.id, timestamp - ORPHAN_REPORT_WINDOW_MS)) continue;
+			// D7 (display-liveness v1): converge the ledger, do not merely report.
+			// `orphan_detected` alone only described a suspicion, so a dead child stayed
+			// `running` forever and every display exit had to special-case it. Commit the
+			// fact first and let the event stream describe a state that already exists:
+			// `liveness()` then reads a terminal row and answers `dead` on its own. `node`
+			// is the pre-convergence snapshot — `updateNode` does not mutate it — so
+			// `node.updatedAt` still names the frozen heartbeat this scan judged.
+			updateNode(this.db, node.id, { status: "failed" }, () => timestamp);
+			appendEvent(this.db, node.id, "node_abandoned", {
+				reason: "no_active_supervisor",
+				staleMs,
+				updatedAt: node.updatedAt,
+			}, { now: () => timestamp });
 			const event = appendEvent(this.db, node.id, "orphan_detected", {
 				parentId: node.parentId,
 				updatedAt: node.updatedAt,

package/src/extension/liveness.ts

@@ -0,0 +1,200 @@
+/**
+ * The single authority for "is this child alive?" (contract
+ * `docs/contracts/display-liveness-v1.md`, D1 / D2 / D5).
+ *
+ * Before this module every display surface answered the question its own way:
+ * the status list looked at `child.state`, the text renderer additionally
+ * computed an owner verdict, and the railway strip arbitrated an event
+ * timestamp against a ledger heartbeat written by a *different* process. The
+ * same child could therefore be `live` (list), `failed` (text) and `running`
+ * (rail) at the same instant. `liveness()` replaces all three with one ordered
+ * projection over the facts available at the moment of rendering.
+ *
+ * ## Order, not union (D1)
+ *
+ * The eight rules below form a *total order* of evidence strength, not a set of
+ * predicates OR'd together. A union would let a leftover `running` ledger row
+ * outvote "this process already knows the child is gone"; the order makes the
+ * stronger evidence win:
+ *
+ * 1. `inMemory` present and non-terminal   → `live`   (we are holding it)
+ * 2. `inMemory` present and terminal       → `dead`
+ * 3. `pidAlive === true`                   → `live`   (a real process runs)
+ * 4. `pidAlive === false`                  → `dead`   (D4: no heartbeat grace)
+ * 5. `ledger` non-terminal, heartbeat fresh → `live`
+ * 6. `ledger` non-terminal, heartbeat stale → `dead`   (orphan; D7 converges it)
+ * 7. `record` terminal                     → `dead`
+ * 8. everything else (incl. all-undefined) → `unknown`
+ *
+ * ## Three states, not two (D2)
+ *
+ * `unknown` exists and must never be rendered as `live`. Treating unknown as
+ * live is exactly the bug that printed `Status · 1 live child` next to
+ * `owner: dead (pid gone)`; treating it as dead would kill children that are
+ * merely starting. The third state is the only honest answer.
+ *
+ * ## Purity (D1, §7-7)
+ *
+ * Pure by construction: no fs, no path, no database, no timer, and **no clock
+ * read**. `now` is a parameter because a module that reads its own clock cannot
+ * be asked "what would this render as at time T" — and two reads at slightly
+ * different times would reintroduce the off-by-a-tick behaviour R2 describes.
+ * `test/unit/liveness.test.ts` asserts these properties by reading this file's
+ * source text.
+ *
+ * ## No timestamp arbitration (D3)
+ *
+ * Nothing here compares timestamps that came from different writers. The only
+ * time comparison is `now - ledger.updatedAt < staleMs`, where `now` is the
+ * caller's render clock and `updatedAt` is that same ledger row's own heartbeat —
+ * one clock family, and the comparison decides freshness rather than "whose
+ * conclusion wins". Event-bus timestamps are never consulted: events only
+ * trigger a recompute (D8).
+ */
+
+/** D2: the three truthful answers. `unknown` is a state, not a synonym for live. */
+export type Liveness = "live" | "dead" | "unknown";
+
+/**
+ * Facts for one child at one instant. Every source is optional because every
+ * source can be absent: a child may exist only in the in-memory registry, only
+ * in the ledger, only in `run.json`, or in none of them (replayed history).
+ */
+export interface LivenessFacts {
+	/** Entry in this process's in-memory child registry, if any. */
+	readonly inMemory?: { readonly state: string } | undefined;
+	/** Ledger row plus the heartbeat timestamp its own process last wrote. */
+	readonly ledger?: { readonly status: string; readonly updatedAt: number } | undefined;
+	/** `run.json` child record (scheduling layer). */
+	readonly record?: { readonly state: string } | undefined;
+	/** Pid-marker verdict; `undefined` means there is no marker to consult. */
+	readonly pidAlive?: boolean | undefined;
+	/** Render clock, supplied by the caller — never read inside this module. */
+	readonly now: number;
+	/** Age after which a non-terminal ledger row is an orphan (default 90s). */
+	readonly staleMs: number;
+}
+
+/**
+ * States that mean "this lifecycle is over". Shared by W1/W2/W4 so the seven
+ * divergent sets listed in R3 collapse into one.
+ *
+ * Note what is *absent*: `idle` and `queued` are non-terminal (D5). An `idle`
+ * child is still alive and still holds a concurrency slot, and a `queued` child
+ * has been admitted but not started — calling either one terminal is what made
+ * the strip paint them as `retired`.
+ */
+export const TERMINAL_STATES: ReadonlySet<string> = new Set([
+	"settled",
+	"success",
+	"completed",
+	"done",
+	"failed",
+	"aborted",
+	"error",
+	"truncated",
+	"retired",
+]);
+
+/** States known to be in flight. `idle`/`queued` are alive: slot held, not working. */
+export const NON_TERMINAL: ReadonlySet<string> = new Set([
+	"starting",
+	"working",
+	"running",
+	"blocked",
+	"idle",
+	"queued",
+]);
+
+/**
+ * A state is terminal only when it is in `TERMINAL_STATES`. Anything unknown —
+ * including `""` — is *not* terminal: we do not get to declare a lifecycle over
+ * because we failed to recognise the label.
+ */
+export function isTerminalState(state: string | undefined): boolean {
+	return state !== undefined && TERMINAL_STATES.has(state.toLowerCase());
+}
+
+/**
+ * D1: one ordered projection over the facts of a single instant.
+ *
+ * Total and side-effect free: the same `facts` always produce the same answer,
+ * which is what makes "render is a projection, not an event replay" (D8)
+ * checkable — see A6.
+ */
+export function liveness(facts: LivenessFacts): Liveness {
+	// 1 + 2: the strongest evidence is a live handle in this very process.
+	const inMemory = facts.inMemory;
+	if (inMemory !== undefined) {
+		return isTerminalState(inMemory.state) ? "dead" : "live";
+	}
+
+	// 3 + 4: an actual OS process. D4 accepts the seconds-wide window where a
+	// just-exited pid still reads alive rather than inventing a grace period.
+	if (facts.pidAlive === true) return "live";
+	if (facts.pidAlive === false) return "dead";
+
+	// 5 + 6: last-written heartbeat. A frozen `updatedAt` from a dead writer is
+	// exactly the orphan case, and staleness is the only timestamp comparison
+	// here — same row, same writer, measuring age instead of ranking writers.
+	//
+	// "Non-terminal" is read as the complement of `TERMINAL_STATES` (D1's wording)
+	// rather than as membership in `NON_TERMINAL`: a row carrying a label we do
+	// not recognise has not told us the lifecycle is over, and rule 8 still keeps
+	// an *absent* ledger out of this branch.
+	const ledger = facts.ledger;
+	if (ledger !== undefined && !isTerminalState(ledger.status)) {
+		return facts.now - ledger.updatedAt < facts.staleMs ? "live" : "dead";
+	}
+
+	// 7 + 8: a terminal verdict from either writer. The ledger row coming first is
+	// D1-a's 2026-10-24 amendment: a ledger row that reached `settled`/`failed`
+	// states a finished lifecycle even when the scheduler record is already gone,
+	// and leaving that case at `unknown` would make the status panel call a
+	// finished child undecided.
+	if (ledger !== undefined && isTerminalState(ledger.status)) return "dead";
+	if (facts.record !== undefined && isTerminalState(facts.record.state)) return "dead";
+
+	// 9: never guess (D2).
+	return "unknown";
+}
+
+/**
+ * The display states a node can take. Declared here rather than in
+ * `src/tui/viz/model.ts` so this module stays dependency-free and every W can
+ * import the mapping without importing the TUI; W4 feeds `VizStatus` with
+ * these values. `idle` and `queued` are new first-class states (D5), and
+ * `unknown` replaces the old `retired` fallback — an unrecognised state must
+ * not be painted as "retired".
+ */
+export type DisplayStatus =
+	| "running"
+	| "idle"
+	| "queued"
+	| "settled"
+	| "failed"
+	| "retired"
+	| "unknown";
+
+const DISPLAY_RUNNING: ReadonlySet<string> = new Set(["starting", "working", "running", "blocked"]);
+const DISPLAY_SETTLED: ReadonlySet<string> = new Set(["settled", "success", "completed", "done"]);
+const DISPLAY_FAILED: ReadonlySet<string> = new Set(["failed", "aborted", "error", "truncated"]);
+
+/**
+ * D5: raw lifecycle state → display state.
+ *
+ * `idle` maps to `idle` and `queued` to `queued` (rendered grey / `queued(n)`),
+ * the four in-flight states collapse to `running`, and everything unrecognised
+ * — including `undefined` — becomes `unknown` rather than the old `retired`
+ * fallback that made a starting child look finished.
+ */
+export function displayStatusFromState(state: string | undefined): DisplayStatus {
+	const value = (state ?? "").toLowerCase();
+	if (value === "idle") return "idle";
+	if (value === "queued") return "queued";
+	if (DISPLAY_SETTLED.has(value)) return "settled";
+	if (DISPLAY_FAILED.has(value)) return "failed";
+	if (DISPLAY_RUNNING.has(value)) return "running";
+	if (value === "retired") return "retired";
+	return "unknown";
+}

package/src/extension/playbook.ts

@@ -15,8 +15,8 @@ export const PARENT_PLAYBOOK = [
 	"5. A collect timeout with a live child is a progress signal, not a verdict. Check status or session JSONL before deciding to steer or resume.",
 	"6. Isolation belongs to centurion. For N parallel isolated writers, dispatch N centurions (each owns one worktree); members stay `worktree: false` in-process. Passing `worktree: true` on a non-centurion warns once and is forced false.",
 	"7. Launch with `verify: [\"npm run typecheck\", \"npm test\"]` when the project has a mechanical verifier. The extension runs those commands itself in the child worktree at collect time; the child does not need to paste test output.",
-	"Utility agents (`utility: true`, e.g. scout) can be dispatched by ANY role via the separate `vexillatio` tool — read-only helpers, always leaf, no depth budget. The `subagent` tool stays for the command chain (worker/centurion).",
-	"Forbidden: direct bash access to legion.db, hand-launching child Pi processes, or using herdr pane/tab/agent commands for dispatch.",
+	"Utility agents (`utility: true`, e.g. scout) can be dispatched by ANY role via the separate `vexillatio` tool — read-only helpers, always leaf, no depth budget. Its request shape matches `subagent`: either `vexillatio({ task, agent? })` or `vexillatio({ tasks: [{ agent, task }, …] })` (no top-level `task` needed; passing both only labels the parent run). The `subagent` tool stays for the command chain (worker/centurion).",
+	"Forbidden: direct bash access to legion.db, or launching child Pi processes by hand (use the subagent tool).",
 ].join("\n");
 
 export const TOOL_DESCRIPTION = [

package/src/extension/recycle.ts

@@ -14,6 +14,10 @@ export function formatAlreadyRecycled(
 
 /** States where collect should return the snapshot already on the child. */
 export function canUseCachedCollect(state: TaskState): boolean {
+	// `queued` is deliberately NOT cacheable (#266 D3/§4.4): the record has no
+	// execution, no acceptance and only a PLACEHOLDER session file, so a cached
+	// collect would hand back a stale/empty snapshot as if the launch had finished.
+	// A queued child must go through `collect`'s wait-for-admission path (D8).
 	return (
 		state === "retired" ||
 		state === "awaiting" ||