pi-legion 3.0.1 → 3.1.0

package/src/extension/runtime.ts

@@ -12,6 +12,7 @@ import {
 	formatCompletionNotice,
 	formatGroupedNotice,
 	collectFailureInput,
+	type CompletionNotice,
 	type SendMessageApi,
 } from "./notify.ts";
 import {
@@ -19,6 +20,7 @@ import {
 	DEFAULT_JOIN_MODE,
 	JoinCoordinator,
 	type JoinConfig,
+	type JoinSchedulerHandle,
 } from "./join.ts";
 import {
 	createStatusBoard,
@@ -32,7 +34,12 @@ import {
 } from "../tui/status.ts";
 import { progressFromSessionFile } from "../shared/progress.ts";
 import { isTransientConnectionFailure } from "../shared/session.ts";
-import { DEFAULTS, type AgentKind, type RetireOptions } from "../shared/types.ts";
+import {
+	DEFAULTS,
+	type AgentKind,
+	type RetireOptions,
+	type SpawnMode,
+} from "../shared/types.ts";
 import type {
 	EventSubscriptionOptions,
 	SupervisorEvent,
@@ -74,6 +81,12 @@ export interface TrackedJobInput {
 	model?: string;
 	thinking?: string | false;
 	worktreeBranch?: string;
+	/**
+	 * Arbitrated backend for this child (`Handle.spawnMode`, #209). Optional:
+	 * a job tracked from a legacy record has no value and must render as
+	 * unknown rather than a guessed `rpc`.
+	 */
+	spawnMode?: SpawnMode;
 	/** Legion tree identity supplied by the host when the M2 ChildRecord is available. */
 	nodeId?: string;
 	parentId?: string | null;
@@ -144,12 +157,48 @@ export interface SessionRuntimeDeps {
 	) => () => void;
 	/** Batching config; applied via setJoinConfig right after construction. */
 	joinConfig?: JoinConfig;
+	/** Injectable timer for the MAX_PENDING_AGE_MS overflow (tests fire it manually); default = unref'd setTimeout. */
+	scheduleNoticeOverflow?: (ms: number, fn: () => void) => JoinSchedulerHandle;
 }
 
 const DEFAULT_REFRESH_MS = 500;
+/**
+ * Hard cap on how long a completion notice may stay hidden behind a live
+ * parent agent run (D-B). 80s = 2× the (1+3)×10s that the old join window
+ * could reach while a busy parent kept extending it. Past this the notice is
+ * force-sent even though the run is still going: reverting to the old
+ * "queued as a followUp" behaviour after 80s is better than hiding it forever.
+ */
+export const MAX_PENDING_AGE_MS = 80_000;
 /** Fallback per-child timeout for wait(); index.ts passes the role value. */
 const DEFAULT_WAIT_TIMEOUT_MS = DEFAULTS.turnTimeoutMs;
 
+/** Default timer for the MAX_PENDING_AGE_MS overflow (unref'd, like join's). */
+function defaultNoticeOverflow(
+	ms: number,
+	fn: () => void,
+): JoinSchedulerHandle {
+	const id = setTimeout(fn, ms);
+	id.unref?.();
+	return { cancel: () => clearTimeout(id) };
+}
+
+/** A completion notice held because the parent agent run is still active (D-A). */
+interface QueuedNotice {
+	notice: CompletionNotice;
+	triggerTurn: boolean;
+	enqueuedAt: number;
+}
+
+export interface NoticeQueueStats {
+	/** Notices currently held. */
+	pending: number;
+	/** now() - enqueuedAt of the oldest held notice; 0 when empty. */
+	oldestAgeMs: number;
+	/** Lifetime count of MAX_PENDING_AGE_MS overflows that forced a send (D-B observability). */
+	forcedFlushes: number;
+}
+
 /** A wait() promise that must settle by the deadline. */
 class WaitTimeoutError extends Error {}
 const WAIT_INTERRUPTED = Symbol("wait interrupted");
@@ -181,8 +230,21 @@ export interface LiveChildStatusInput {
 		usage?: { input: number; output: number; cost: number } | null;
 	};
 	acceptance?: { status: string; level?: string };
+	/**
+	 * Backend the child was actually spawned on (#209). Absent for records written
+	 * before run.json carried it, and for tree-only fallbacks — renders `unknown`,
+	 * never a guessed `rpc`.
+	 */
+	spawnMode?: string;
 	/** RPC process is still running. */
 	alive: boolean;
+	/**
+	 * Run-dir ownership verdict (#209-3), from `owner.json`.
+	 * `alive` is this process's in-memory child registry, which never contains
+	 * a child launched by another session — so a foreign record must be judged
+	 * by the owner marker instead. Only consulted when `alive` is false.
+	 */
+	owner?: "live" | "dead" | "unknown";
 	now?: number;
 }
 
@@ -245,6 +307,12 @@ function formatExecutionStatusLine(
 	return `${label}: ${execution.status}${execution.reason ? ` (${execution.reason})` : ""}`;
 }
 
+/** One-line ownership verdict appended to a status block (#209-3). */
+function ownerLine(owner: "live" | "dead" | "unknown"): string {
+	if (owner === "dead") return "owner: dead (pid gone)";
+	return `owner: ${owner}`;
+}
+
 /**
  * Status text for one child (`/legion status <name>` and `subagent status`).
  *
@@ -257,7 +325,15 @@ function formatExecutionStatusLine(
  */
 export function renderLiveChildStatus(input: LiveChildStatusInput): string {
 	const stale = persistedSnapshotIsStale(input);
-	const state = stale ? "working" : input.state;
+	// #209-3: a persisted `working` snapshot whose run-dir owner pid is gone is
+	// dead, not working. `stale` (alive process + retired/failed snapshot) keeps
+	// owning the opposite direction, so the two never fight over one record.
+	const ownerDead = input.owner === "dead" && !input.alive;
+	const state = stale
+		? "working"
+		: ownerDead && input.state === "working"
+			? "failed"
+			: input.state;
 	const execution = stale
 		? { status: "running", reason: "rpc child alive", usage: input.execution?.usage }
 		: input.execution;
@@ -268,9 +344,11 @@ export function renderLiveChildStatus(input: LiveChildStatusInput): string {
 		const age = lastJsonlEventAgeMs(input.sessionFile, input.now ?? Date.now());
 		lines.push(formatAliveQuiet(age));
 	}
+	// After the liveness lead: who owns the run dir, and whether that pid is gone.
+	if (input.owner !== undefined) lines.push(ownerLine(input.owner));
 	// Quiet age first; path metadata after snapshots so old store lines stay below.
 	const meta = [
-		"supervisor=rpc",
+		`supervisor=${input.spawnMode ?? "unknown"}`,
 		`session=${input.sessionFile}`,
 	];
 	if (execution) {
@@ -356,6 +434,12 @@ export interface SessionRuntime {
 	statusTui(): WidgetTui | undefined;
 	/** Forward join config to the internal coordinator (settings wiring). */
 	setJoinConfig(config: JoinConfig): void;
+	/** Parent agent run started (pi `agent_start`): hold completion notices until settle (D-A/D-C). */
+	notifyParentRunStart(): void;
+	/** Parent agent run settled (pi `agent_settled`): send every held notice now, then repaint (D-A/D-D). */
+	notifyParentSettled(): void;
+	/** Introspection seam for tests/doctor: deferred-notice queue state (D-B observability). */
+	noticeQueueStats(): NoticeQueueStats;
 	/**
 	 * Explicit wait: suppress auto-notify on the targets via consumedByTool
 	 * and aggregate their results. A timeout restores auto-notify.
@@ -400,6 +484,92 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 		mode: DEFAULT_JOIN_MODE,
 		flushMs: DEFAULT_FLUSH_MS,
 	};
+
+	// Run-scoped completion outbox (D-A). The host only drains
+	// `agent.followUpQueue` inside a live run, so a `followUp` sent while the
+	// parent run is active sits invisible until the user types again. When a
+	// run is active we therefore hold the formatted notice here and burst it
+	// out on `agent_settled` (D-D). This is the ONLY deferral point: the join
+	// window above batches stragglers and never waits on a busy parent (D-I).
+	//
+	// D-H: the default is `false`, so a host (or a test) that never signals a
+	// run start keeps today's immediate-send behaviour byte for byte.
+	let parentRunActive = false;
+	const outbox: QueuedNotice[] = [];
+	let outboxTimer: JoinSchedulerHandle | undefined;
+	let forcedFlushes = 0;
+
+	const armOutboxTimer = (): void => {
+		if (outboxTimer || outbox.length === 0 || disposed) return;
+		const oldest = outbox[0]!;
+		const delay = Math.max(0, oldest.enqueuedAt + MAX_PENDING_AGE_MS - now());
+		// `live` proves this callback is the CURRENT arm. A cancelled-but-still-
+		// invoked timer (a zombie queued before the cancel landed) must be a strict
+		// no-op: otherwise it would clear the live timer's handle and force-send a
+		// notice that is nowhere near its cap.
+		//
+		// A boolean — not a closure over the handle — because an injected scheduler
+		// is free to invoke the callback synchronously, before the `const` binding
+		// is initialized (TDZ). `live` is assigned above the call, so it is always
+		// safe to read from inside the callback.
+		let live = true;
+		const handle: JoinSchedulerHandle = (deps.scheduleNoticeOverflow ?? defaultNoticeOverflow)(delay, () => {
+			if (!live) return;
+			live = false;
+			outboxTimer = undefined;
+			if (outbox.length === 0) return;
+			const next = outbox[0]!;
+			if (now() < next.enqueuedAt + MAX_PENDING_AGE_MS) {
+				// Fired while the oldest notice is still younger than the cap (a
+				// coarse timer or a backwards clock step). Never force-send early:
+				// re-arm for the remaining age instead.
+				armOutboxTimer();
+				return;
+			}
+			forcedFlushes += 1;
+			flushOutbox();
+		});
+		outboxTimer = {
+			cancel: () => {
+				live = false;
+				handle.cancel();
+			},
+		};
+	};
+
+	// FIFO, one message per notice: the grouped shape belongs to the join layer.
+	// N held notices = N host `_runAgentPrompt` calls; the common case is 1 per
+	// run, so the batch is not merged into a synthetic grouped notice.
+	const flushOutbox = (): void => {
+		outboxTimer?.cancel();
+		outboxTimer = undefined;
+		if (outbox.length === 0) return;
+		// One splice: anything enqueued by a re-entrant send belongs to the next
+		// batch, so a settle can never double-deliver what it already flushed.
+		const batch = outbox.splice(0);
+		for (const item of batch) {
+			// A rejected send is dropped, not requeued (same as before).
+			deliverCompletion(
+				{ sendMessage: deps.sendMessage },
+				item.notice,
+				item.triggerTurn,
+			);
+		}
+	};
+
+	/** The single completion exit: send now, or hold until the run settles. */
+	const sendCompletionNotice = (
+		notice: CompletionNotice,
+		triggerTurn: boolean,
+	): void => {
+		if (!parentRunActive) {
+			deliverCompletion({ sendMessage: deps.sendMessage }, notice, triggerTurn);
+			return;
+		}
+		outbox.push({ notice, triggerTurn, enqueuedAt: now() });
+		armOutboxTimer();
+	};
+
 	const join = new JoinCoordinator({
 		deliver: (batch) => {
 			if (disposed) return;
@@ -415,8 +585,7 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 				batch.length === 1 &&
 				(joinConfig.mode === "each" || join.allSettled(first.runId))
 			) {
-				deliverCompletion(
-					{ sendMessage: deps.sendMessage },
+				sendCompletionNotice(
 					formatCompletionNotice(first.input),
 					first.triggerTurn,
 				);
@@ -435,8 +604,7 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 						!batch.some((e) => e.name === job.name),
 				)
 				.map((job) => job.name);
-			deliverCompletion(
-				{ sendMessage: deps.sendMessage },
+			sendCompletionNotice(
 				formatGroupedNotice({
 					runId: first.runId,
 					entries: batch.map((e) => ({ ...e.input, status: e.status })),
@@ -472,7 +640,30 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 			for (const nodeId of activity.keys()) if (!tree.has(nodeId)) activity.delete(nodeId);
 			for (const nodeId of eventOverrides.keys()) if (!tree.has(nodeId)) eventOverrides.delete(nodeId);
 		}
-		return [...tree.values()].map((node) => ({ ...node }));
+		const nodes = [...tree.values()].map((node) => ({ ...node }));
+		return mergeSpawnModes(nodes);
+	};
+
+	/**
+	 * #209/D5: the arbitrated backend lives on the tracked job, never in
+	 * legion.db (no column, no migration), so it is merged onto the matching
+	 * snapshot. Unmatched jobs contribute nothing rather than a guess.
+	 *
+	 * Shared by `snapshotNodes()` and `treeNodes()`: the latter synthesizes
+	 * nodes of its own (a job with identity but no DB row yet) and returns that
+	 * array directly, so a merge that only ran in `snapshotNodes()` would drop
+	 * the mode in the pre-DB-row window and in a plain session where
+	 * `getTreeNodes()` yields `[]`.
+	 */
+	const mergeSpawnModes = (
+		nodes: TreeNodeSnapshot[],
+	): TreeNodeSnapshot[] => {
+		for (const job of jobs.values()) {
+			if (job.spawnMode === undefined) continue;
+			const match = storedNodeForJob(job, nodes);
+			if (match) match.spawnMode = job.spawnMode;
+		}
+		return nodes;
 	};
 
 	const storedNodeForJob = (
@@ -812,6 +1003,9 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 				existing.model = input.model;
 				existing.thinking = input.thinking;
 				existing.worktreeBranch = input.worktreeBranch;
+				// Only a known value overwrites: a re-follow without the handle must
+				// not erase the mode an earlier launch established.
+				if (input.spawnMode !== undefined) existing.spawnMode = input.spawnMode;
 				if (input.nodeId !== undefined || identity.nodeId !== undefined) existing.nodeId = input.nodeId ?? identity.nodeId;
 				if (input.parentId !== undefined || identity.parentId !== undefined) existing.parentId = input.parentId ?? identity.parentId;
 				if (input.depth !== undefined || identity.depth !== undefined) existing.depth = input.depth ?? identity.depth;
@@ -867,6 +1061,10 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 					job.notified = false;
 					job.consumedByTool = false;
 					join.addPending(job.runId, job.name);
+					// Repaint before the new watch takes over so the panel cannot
+					// hold the old row's final second. watch() repaints too; this is
+					// an idempotent second guarantee.
+					refreshUi();
 					runtime.watch(name, opts);
 				};
 				try {
@@ -914,6 +1112,9 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 					}
 					job.state = "awaiting";
 					job.settledAt = now();
+					// Repaint immediately: the row flips to a terminal state here, and
+					// waiting for the 500ms sampler leaves a phantom "working" row.
+					refreshUi();
 					if (!job.consumedByTool && !job.notified) {
 						job.notified = true;
 						join.onTerminal({
@@ -959,6 +1160,7 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 					}
 					job.state = "awaiting";
 					job.settledAt = now();
+					refreshUi();
 					if (!job.consumedByTool && !job.notified) {
 						job.notified = true;
 						// Collect failures join the batch too, as a failed entry.
@@ -1143,7 +1345,10 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 				if (index >= 0) result[index] = next;
 				else result.push(next);
 			}
-			return result;
+			// The synthesized nodes above are built from job facts, not from a DB
+			// row, so they carry no `spawnMode` of their own: run the same merge
+			// the snapshot path uses before handing the array out (#209/D5).
+			return mergeSpawnModes(result);
 		},
 
 		statusEntries() {
@@ -1157,6 +1362,25 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 			join.setConfig(config);
 		},
 
+		notifyParentRunStart() {
+			parentRunActive = true;
+		},
+
+		notifyParentSettled() {
+			parentRunActive = false;
+			flushOutbox();
+			refreshUi();
+		},
+
+		noticeQueueStats(): NoticeQueueStats {
+			const oldest = outbox[0];
+			return {
+				pending: outbox.length,
+				oldestAgeMs: oldest ? Math.max(0, now() - oldest.enqueuedAt) : 0,
+				forcedFlushes,
+			};
+		},
+
 		async wait(names, opts = {}) {
 			return Promise.all(
 				names.map((name) =>
@@ -1194,6 +1418,12 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 			jobs.clear();
 			finished.clear();
 			join.dispose();
+			// Shutdown drops held notices unsent: the child's session file survives,
+			// so `collect` can still recover the result from disk. The `finished`
+			// cache does NOT survive — it was cleared two statements up.
+			outboxTimer?.cancel();
+			outboxTimer = undefined;
+			outbox.length = 0;
 			if (timer) clearInterval(timer);
 			timer = undefined;
 			for (const unsubscribe of busUnsubscribers) unsubscribe();
@@ -1289,6 +1519,13 @@ function statusEntryFromNode(
 		activity?.turnStartedAt,
 		activity?.turnEndedAt,
 	);
+	// An in-process child has no tracked job for its whole first run: spawnChild()
+	// awaits the whole agent run, so the job (and its sessionFile plumbing in
+	// statusEntryFromJob) does not exist yet. The node row does carry the session
+	// file, so parse it directly — otherwise the ledger only has a tokens_out row
+	// after settle and the token rate reads 0 for the agent's entire lifetime.
+	const live = node.sessionFile ? progressFromSessionFile(node.sessionFile) : {};
+	const tokensOut = live.tokensOut ?? node.tokensOut;
 	return {
 		name: node.name,
 		agent: node.role,
@@ -1300,8 +1537,9 @@ function statusEntryFromNode(
 		...(node.phase ? { phase: node.phase } : {}),
 		...(node.kind ? { kind: node.kind } : {}),
 		...(node.model ? { model: node.model } : {}),
-		...(node.tokensTotal ? { tokensTotal: node.tokensTotal } : {}),
-		...(node.tokensOut ? { tokensOut: node.tokensOut } : {}),
+		...(live.usageTotal ? { tokensTotal: live.usageTotal } : node.tokensTotal ? { tokensTotal: node.tokensTotal } : {}),
+		...(tokensOut ? { tokensOut } : {}),
+		...(live.generationMs ? { generationMs: live.generationMs } : {}),
 		...(activity?.turn !== undefined ? { turns: activity.turn } : {}),
 		...(activity?.turnStartedAt !== undefined ? { currentTurnStartedAt: activity.turnStartedAt } : {}),
 		...(activity?.turnEndedAt !== undefined ? { currentTurnEndedAt: activity.turnEndedAt } : {}),

package/src/extension/spawn-hints.ts

@@ -3,12 +3,16 @@
  * so `/legion doctor` / `subagent action=diagnose` can show what just broke.
  */
 
+import type { SpawnMode } from "../shared/types.ts";
+
 export interface SpawnFailureRecord {
 	ts: number;
 	name: string;
 	message: string;
 	stderr?: string;
 	hadNoExtensions?: boolean;
+	/** When known, doctor / hints can avoid RPC-only advice for inprocess (#212). */
+	spawnMode?: SpawnMode;
 }
 
 const MAX_FAILURES = 8;
@@ -29,21 +33,35 @@ export function clearSpawnFailures(): void {
 }
 
 const MODEL_NOT_FOUND =
-	/Model\s+"[^"]+"\s+not found|No models available|Use --list-models/i;
+	/Model\s+"[^"]+"\s+not found|No models available|Use --list-models|Unknown provider|inprocess model resolve failed/i;
 
 export function looksLikeMissingModel(stderr: string | undefined): boolean {
 	return Boolean(stderr && MODEL_NOT_FOUND.test(stderr));
 }
 
+/** Inprocess children have no argv; point at models.json / role extensions (#212). */
+export const INPROCESS_MODEL_HINT =
+	"Hint: default spawnMode is `inprocess` — children resolve models via ModelRuntime, " +
+	"not a `--no-extensions` argv.\n" +
+	"Fix: declare the provider statically in `models.json` (agent dir / project), " +
+	"list the extension under the role's `extensions:` frontmatter, or set " +
+	"`inheritExtensions: true` / `PI_LEGION_CHILD_INHERIT_EXTENSIONS=1`. " +
+	"Run `/legion doctor` or `subagent action=diagnose`.";
+
 /**
- * When a child dies because its model/provider is invisible under
- * `--no-extensions`, point at the escape hatches and `/legion doctor`.
+ * When a child dies because its model/provider is invisible, point at the
+ * right escape hatch for the spawn backend (`rpc` argv vs `inprocess`).
  */
 export function spawnFailureHint(input: {
 	stderr?: string;
 	args?: readonly string[];
+	/** Prefer this when known; inprocess never gets argv / CHILD_EXTENSIONS advice (#212). */
+	spawnMode?: SpawnMode;
 }): string | undefined {
 	if (!looksLikeMissingModel(input.stderr)) return undefined;
+	if (input.spawnMode === "inprocess") {
+		return INPROCESS_MODEL_HINT;
+	}
 	const noExt = input.args?.includes("--no-extensions") ?? true;
 	if (!noExt) {
 		return (
@@ -67,13 +85,16 @@ export function withSpawnFailureHint(message: string, input: {
 	stderr?: string;
 	args?: readonly string[];
 	name?: string;
+	spawnMode?: SpawnMode;
 }): string {
 	const hint = spawnFailureHint(input);
 	recordSpawnFailure({
 		name: input.name ?? "?",
 		message,
 		stderr: input.stderr,
-		hadNoExtensions: input.args?.includes("--no-extensions"),
+		hadNoExtensions:
+			input.spawnMode === "inprocess" ? false : input.args?.includes("--no-extensions"),
+		spawnMode: input.spawnMode,
 	});
 	return hint ? `${message}\n\n${hint}` : message;
 }

package/src/extension/spawn-render.ts

@@ -0,0 +1,183 @@
+/**
+ * TUI renderer for the `subagent` / `vexillatio` tool results.
+ *
+ * Pi never renders a tool result's `details` on its own: `renderResult` is the
+ * only consumer, and a tool registered without one falls back to the plain
+ * `content` text. So the arbitrated `spawnMode` (#209) stays invisible until a
+ * renderer names it — that is all this file does.
+ *
+ * The summary line is derived from `details`, never from `content`: `content`
+ * is model-facing, `details` is TUI-facing (`docs/design.md:258`). Keeping the
+ * line out of `content` keeps it out of the LLM context.
+ *
+ * Renderers are called on every repaint, so nothing here may throw: the host
+ * swallows a throwing renderer and falls back to the default block, silently
+ * erasing the very fact this file exists to show. Every `details` read is
+ * therefore optional-chained and shape-checked, AND both entry points are
+ * wrapped in `try/catch`: a shape check is no defence against a getter or a
+ * Proxy trap that throws (host: `tool-execution.js` catch → fallback card).
+ */
+
+import { Text } from "@earendil-works/pi-tui";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { stripTerminalSequences } from "@earendil-works/pi-tui";
+
+/** How many `content` lines a collapsed card keeps before the expand hint. */
+const COLLAPSED_LINES = 10;
+
+const SPAWN_MODES = new Set(["rpc", "inprocess"]);
+
+/**
+ * Binary control bytes that must never reach the terminal renderer.
+ *
+ * Same set as the host fallback (`shell.js:sanitizeBinaryOutput`, used by
+ * `render-utils.js:getTextOutput`): TAB, LF and CR are excluded on purpose —
+ * the carriage return is a line break here, see {@link resultLines}.
+ */
+const BINARY_CONTROL = /[\x00-\x08\x0B\x0C\x0E-\x1F\uFFF9-\uFFFB]/g;
+
+export interface SpawnRenderOptions {
+	expanded: boolean;
+	isPartial: boolean;
+}
+
+function isSpawnMode(value: unknown): value is "rpc" | "inprocess" {
+	return typeof value === "string" && SPAWN_MODES.has(value);
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return typeof value === "object" && value !== null
+		? (value as Record<string, unknown>)
+		: undefined;
+}
+
+/** One `name=mode` entry from a `spawns[]` array (launch-family details). */
+function entryFromSpawn(value: unknown): string | undefined {
+	const spawn = asRecord(value);
+	if (!spawn) return undefined;
+	const name = spawn.name;
+	const mode = spawn.spawnMode;
+	if (typeof name !== "string" || !name) return undefined;
+	// An unknown/absent mode is skipped, never printed as a guess: a legacy
+	// handle must render as "no fact", not as `rpc`.
+	if (!isSpawnMode(mode)) return undefined;
+	return `${name}=${mode}`;
+}
+
+/** One `name=mode` entry from a `handles[]` object (vexillatio details). */
+function entryFromHandle(value: unknown): string | undefined {
+	const handle = asRecord(value);
+	if (!handle) return undefined;
+	return entryFromSpawn(handle);
+}
+
+/**
+ * `spawn: scout-0=inprocess` or `spawn: worker-0=rpc, scout-1=inprocess`.
+ *
+ * Reads both documented detail shapes defensively:
+ * - launch family: `details.spawns[]` (`{ name, agent, spawnMode }`)
+ * - vexillatio:    `details.handles[]` (`{ name, agent, sessionFile, spawnMode? }`)
+ *
+ * One entry per child, first occurrence wins: a result that carries the same
+ * handle in both arrays must not print `w=rpc, w=rpc`.
+ *
+ * Returns `undefined` when nothing survives — no details, wrong shape, or every
+ * entry's mode unknown. Unknown modes are omitted rather than defaulted.
+ *
+ * Never throws: a `details` object with a throwing getter (or a Proxy) would
+ * otherwise take the whole card down, because the host swallows renderer
+ * exceptions and paints its fallback instead.
+ */
+export function spawnModeSummary(details: unknown): string | undefined {
+	try {
+		const record = asRecord(details);
+		if (!record) return undefined;
+		const entries: string[] = [];
+		const seen = new Set<string>();
+		const push = (entry: string | undefined): void => {
+			if (!entry || seen.has(entry)) return;
+			seen.add(entry);
+			entries.push(entry);
+		};
+		const spawns = record.spawns;
+		if (Array.isArray(spawns)) {
+			for (const spawn of spawns) push(entryFromSpawn(spawn));
+		}
+		// `handles` may be a `string[]` (launch-family) or an object array
+		// (vexillatio); string entries simply never match, so both shapes pass.
+		const handles = record.handles;
+		if (Array.isArray(handles)) {
+			for (const handle of handles) push(entryFromHandle(handle));
+		}
+		if (entries.length === 0) return undefined;
+		return `spawn: ${entries.join(", ")}`;
+	} catch {
+		// A hostile/throwing getter is not a rendering failure: no fact, no line.
+		return undefined;
+	}
+}
+
+/**
+ * The model-facing text of a result, normalized the way it will be painted.
+ *
+ * Line counting has to happen on the text that actually renders, so
+ * normalizing runs BEFORE the split: a carriage return is how a progress
+ * stream redraws one line, not 20 rows — but `Text` treats `\r` as a line
+ * break, so leaving it in lets 20 segments paint 20 rows and bypass
+ * {@link COLLAPSED_LINES} with no hint. `\r` therefore becomes `\n` (so all
+ * 20 segments stay readable instead of being concatenated into one blob) and
+ * binary control bytes are dropped, matching the host fallback's intent
+ * (`render-utils.js:40` sanitizes binary output and removes raw `\r`).
+ */
+function resultLines(result: AgentToolResult<unknown> | undefined): string[] {
+	const content = result?.content;
+	if (!Array.isArray(content)) return [];
+	const text = content
+		.flatMap((part) => {
+			if (asRecord(part)?.type !== "text") return [];
+			const value = asRecord(part)?.text;
+			return typeof value === "string" ? [value] : [];
+		})
+		.join("\n");
+	const normalized = stripTerminalSequences(text)
+		.replace(/\r\n/g, "\n")
+		.replace(/\r/g, "\n")
+		.replace(BINARY_CONTROL, "");
+	return normalized.split("\n");
+}
+
+/**
+ * Build the card: the spawn summary line (when known) followed by the result
+ * text, capped at {@link COLLAPSED_LINES} lines until `ctrl+o` expands it.
+ *
+ * Never throws by design; see the file comment.
+ */
+export function renderSpawnResult(
+	result: AgentToolResult<unknown>,
+	opts: SpawnRenderOptions,
+	_theme: Theme,
+) {
+	const lines: string[] = [];
+	// Double insurance: `spawnModeSummary` is already total, but this call site
+	// must not depend on the callee's implementation staying that way (the host
+	// silences a throw and drops the card). The `details` READ is inside the
+	// guard too — a Proxy can throw on the property access itself.
+	let summary: string | undefined;
+	try {
+		summary = spawnModeSummary(result?.details);
+	} catch {
+		summary = undefined;
+	}
+	if (summary) lines.push(summary);
+	lines.push(...resultLines(result));
+	// `opts` is host-supplied; optional-chained so a partial/absent options
+	// object degrades to the collapsed view instead of throwing.
+	if (opts?.expanded || lines.length <= COLLAPSED_LINES) {
+		return new Text(lines.join("\n"), 0, 0);
+	}
+	const hidden = lines.length - COLLAPSED_LINES;
+	const visible = lines.slice(0, COLLAPSED_LINES);
+	visible.push(`... (${hidden} more lines, ctrl+o to expand)`);
+	return new Text(visible.join("\n"), 0, 0);
+}