taskplane 0.28.4 → 0.28.6

package/extensions/taskplane/agent-host.ts

@@ -1,745 +1,833 @@
-/**
- * Agent Host — Direct-child Pi agent hosting for Runtime V2
- *
- * Spawns `pi --mode rpc` as a direct child process (no terminal multiplexer, no shell),
- * parses RPC JSONL events, normalizes them into RuntimeAgentEvents,
- * manages mailbox delivery, and produces exit summaries.
- *
- * This replaces the legacy terminal-session hosting path with
- * a programmatic parent-child model where the caller has full process
- * ownership.
- *
- * Key differences from the legacy path:
- *   1. No terminal-session backend — `spawn()` with `shell: false`
- *   2. No sidecar tailing — events flow directly to the caller via callbacks
- *   3. No PID-file orphan guessing — caller owns the process handle
- *   4. Registry integration — manifests updated on status transitions
- *   5. Pi CLI resolved to JS entrypoint, not .CMD shim
- *
- * @module taskplane/agent-host
- * @since TP-104
- */
-
-import { spawn, type ChildProcess } from "child_process";
-import {
-	readFileSync, writeFileSync, appendFileSync, mkdirSync,
-	existsSync, readdirSync, renameSync,
-} from "fs";
-import { join, dirname, basename, resolve } from "path";
-import { StringDecoder } from "string_decoder";
-
-import type {
-	RuntimeAgentId,
-	RuntimeAgentRole,
-	RuntimeAgentEvent,
-	RuntimeAgentEventType,
-	RuntimeAgentManifest,
-	PacketPaths,
-} from "./types.ts";
-
-import {
-	createManifest,
-	writeManifest,
-	updateManifestStatus,
-	buildRegistrySnapshot,
-	writeRegistrySnapshot,
-} from "./process-registry.ts";
-import { appendMailboxAuditEvent } from "./mailbox.ts";
-import { resolvePiCliPath } from "./path-resolver.ts";
-
-// ── Pi CLI Resolution ────────────────────────────────────────────────
-// resolvePiCliPath() is imported from path-resolver.ts and re-exported below (TP-157)
-
-export { resolvePiCliPath };
-// ── Conversation Payload Helpers (TP-111) ───────────────────────────────
-
-/** Maximum characters for conversation event text payloads. */
-const MAX_CONV_PAYLOAD_CHARS = 2000;
-
-/** Truncate a string to maxLen chars, appending ellipsis if truncated. */
-function truncatePayload(text: string, maxLen: number): string {
-	if (text.length <= maxLen) return text;
-	return text.slice(0, maxLen) + "…";
-}
-
-/**
- * Extract text content from a Pi RPC message_end event's message object.
- * Pi may return content as a string or as an array of content blocks.
- */
-function extractAssistantText(message: Record<string, unknown>): string {
-	// Direct string content
-	if (typeof message.content === "string") return message.content;
-	// Array of content blocks (Anthropic format)
-	// Guard: skip null/non-object entries to prevent TypeError on malformed streams
-	if (Array.isArray(message.content)) {
-		const textBlocks = message.content
-			.filter((b: unknown): b is { type: string; text: string } =>
-				typeof b === "object" && b !== null &&
-				(b as any).type === "text" && typeof (b as any).text === "string")
-			.map((b) => b.text);
-		if (textBlocks.length > 0) return textBlocks.join("\n");
-	}
-	// Fallback: try text field
-	if (typeof message.text === "string") return message.text;
-	return "";
-}
-
-// ── Types ────────────────────────────────────────────────────────────
-
-/**
- * Options for spawning an agent via the direct host.
- *
- * @since TP-104
- */
-export interface AgentHostOptions {
-	/** Stable agent identity */
-	agentId: RuntimeAgentId;
-	/** Agent role */
-	role: RuntimeAgentRole;
-	/** Batch ID this agent belongs to */
-	batchId: string;
-	/** Lane number (null for merge agents) */
-	laneNumber: number | null;
-	/** Task ID being executed (null before first assignment) */
-	taskId: string | null;
-	/** Repo ID the agent is operating in */
-	repoId: string;
-	/** Working directory for the Pi process */
-	cwd: string;
-	/** User prompt content */
-	prompt: string;
-	/** Optional system prompt content */
-	systemPrompt?: string;
-	/** Model identifier (e.g., "anthropic/claude-sonnet-4-20250514") */
-	model?: string;
-	/** Comma-separated tool list */
-	tools?: string;
-	/** Thinking mode override */
-	thinking?: string;
-	/** Extension paths to load */
-	extensions?: string[];
-	/** Mailbox directory for steering (null = no mailbox) */
-	mailboxDir?: string | null;
-	/** Steering-pending JSONL path (TP-090, worker-only) */
-	steeringPendingPath?: string | null;
-	/** Path to persist normalized events JSONL */
-	eventsPath?: string | null;
-	/** Path to write exit summary JSON */
-	exitSummaryPath?: string | null;
-	/** Timeout in milliseconds (0 = no timeout) */
-	timeoutMs?: number;
-	/** Delay in ms before closing stdin after agent_end (default: 100) */
-	closeDelayMs?: number;
-	/** State root for process registry (null = no registry integration) */
-	stateRoot?: string | null;
-	/** Packet paths for registry manifest (null for merge agents) */
-	packet?: PacketPaths | null;
-	/** Extra environment variables for the child process */
-	env?: Record<string, string>;
-	/**
-	 * Callback invoked when agent_end fires, before stdin is closed.
-	 * Receives the last assistant message text.
-	 * Return a string to send as a new prompt (re-prompt the agent),
-	 * or null to close the session normally.
-	 *
-	 * @since TP-172
-	 */
-	onPrematureExit?: (assistantMessage: string) => Promise<string | null>;
-	/**
-	 * Maximum number of exit interceptions before forcing session close.
-	 * Prevents infinite loops where the callback always returns a new prompt.
-	 * Default: 2
-	 *
-	 * @since TP-172
-	 */
-	maxExitInterceptions?: number;
-}
-
-/**
- * Accumulated telemetry from a completed agent session.
- *
- * @since TP-104
- */
-export interface AgentHostResult {
-	/** Process exit code (null if killed by signal) */
-	exitCode: number | null;
-	/** Signal that killed the process (null if exited normally) */
-	signal: string | null;
-	/** Wall-clock duration in milliseconds */
-	durationMs: number;
-	/** Whether the process was killed by the caller */
-	killed: boolean;
-	/** Total input tokens */
-	inputTokens: number;
-	/** Total output tokens */
-	outputTokens: number;
-	/** Cache read tokens */
-	cacheReadTokens: number;
-	/** Cache write tokens */
-	cacheWriteTokens: number;
-	/** Cumulative cost in USD */
-	costUsd: number;
-	/** Number of tool calls */
-	toolCalls: number;
-	/** Last tool call description */
-	lastTool: string;
-	/** Number of auto-retries */
-	retries: number;
-	/** Number of auto-compactions */
-	compactions: number;
-	/** Authoritative context usage from Pi */
-	contextUsage: { tokens: number; contextWindow: number; percent: number } | null;
-	/** Final error message (null if clean exit) */
-	error: string | null;
-	/** Whether agent_end was received */
-	agentEnded: boolean;
-	/** Captured stderr tail (last 2KB) */
-	stderrTail: string;
-}
-
-/**
- * Callback for normalized agent events.
- *
- * @since TP-104
- */
-export type AgentEventCallback = (event: RuntimeAgentEvent) => void;
-
-/**
- * Callback for telemetry updates (called on each message_end).
- *
- * @since TP-104
- */
-export type AgentTelemetryCallback = (result: Partial<AgentHostResult>) => void;
-
-// ── JSONL Helpers ────────────────────────────────────────────────────
-
-const MAILBOX_MESSAGE_TYPES = new Set(["steer", "query", "abort", "info", "reply", "escalate"]);
-
-function isValidMailboxMessage(obj: any): boolean {
-	if (!obj || typeof obj !== "object") return false;
-	return (
-		typeof obj.id === "string" &&
-		typeof obj.batchId === "string" &&
-		typeof obj.from === "string" &&
-		typeof obj.to === "string" &&
-		typeof obj.timestamp === "number" && Number.isFinite(obj.timestamp) &&
-		typeof obj.type === "string" && MAILBOX_MESSAGE_TYPES.has(obj.type) &&
-		typeof obj.content === "string"
-	);
-}
-
-// ── Core Host Function ───────────────────────────────────────────────
-
-/**
- * Spawn and manage a Pi agent as a direct child process.
- *
- * Returns a promise that resolves with the full session result when
- * the agent exits, plus a kill function for early termination.
- *
- * @param opts - Agent host options
- * @param onEvent - Optional callback for normalized events
- * @param onTelemetry - Optional callback for telemetry updates
- * @returns Object with promise (resolves on exit) and kill function
- *
- * @since TP-104
- */
-export function spawnAgent(
-	opts: AgentHostOptions,
-	onEvent?: AgentEventCallback,
-	onTelemetry?: AgentTelemetryCallback,
-): { promise: Promise<AgentHostResult>; kill: () => void } {
-
-	const cliPath = resolvePiCliPath();
-	const closeDelayMs = opts.closeDelayMs ?? 100;
-	const timeoutMs = opts.timeoutMs ?? 0;
-	const maxExitInterceptions = opts.maxExitInterceptions ?? 3;
-
-	// Build Pi CLI arguments
-	const piArgs: string[] = [cliPath, "--mode", "rpc", "--no-session"];
-	if (opts.model) piArgs.push("--model", opts.model);
-	if (opts.tools) piArgs.push("--tools", opts.tools);
-	if (opts.systemPrompt) piArgs.push("--system-prompt", opts.systemPrompt);
-	// Always pass --no-extensions to prevent auto-discovery from cwd.
-	// Explicit -e entries are still honored by pi even with --no-extensions.
-	// This matches the fix from TP-095 that eliminated duplicate extension loading.
-	piArgs.push("--no-extensions");
-	if (opts.extensions && opts.extensions.length > 0) {
-		for (const ext of opts.extensions) {
-			piArgs.push("-e", ext);
-		}
-	}
-	piArgs.push("--no-skills");
-	if (opts.thinking) piArgs.push("--thinking", opts.thinking);
-
-	// Spawn directly — no shell, no terminal multiplexer
-	const proc = spawn(process.execPath, piArgs, {
-		shell: false,
-		cwd: opts.cwd,
-		stdio: ["pipe", "pipe", "pipe"],
-		env: { ...process.env, ...(opts.env ?? {}) },
-	});
-
-	// State accumulator
-	const startedAt = Date.now();
-	let killed = false;
-	let timedOut = false;
-	let agentEnded = false;
-	let stdinClosed = false;
-	let assistantMessageEnds = 0;
-	const STATS_REFRESH_EVERY_ASSISTANT_MESSAGES = 5;
-	let inputTokens = 0, outputTokens = 0, cacheReadTokens = 0, cacheWriteTokens = 0;
-	let costUsd = 0, toolCalls = 0, retries = 0, compactions = 0;
-	let lastTool = "", error: string | null = null;
-	let contextUsage: AgentHostResult["contextUsage"] = null;
-	let stderrBuffer = "";
-	const STDERR_MAX = 2048;
-	/** Last assistant message text captured from message_end events (TP-172) */
-	let lastAssistantMessage = "";
-	/** Number of times exit interception has occurred (TP-172) */
-	let exitInterceptionCount = 0;
-	/** Whether the current turn had any tool calls (TP-172: text-only gate) */
-	let currentTurnHadToolCalls = false;
-
-	// Timeout
-	let timeoutHandle: ReturnType<typeof setTimeout> | null = null;
-	if (timeoutMs > 0) {
-		timeoutHandle = setTimeout(() => {
-			timedOut = true;
-			killed = true;
-			try { proc.kill("SIGTERM"); } catch { /* ignore */ }
-		}, timeoutMs);
-	}
-
-	const REGISTRY_REFRESH_INTERVAL_MS = 1_000;
-	let lastRegistryRefreshAt = 0;
-	const refreshRegistrySnapshot = (force: boolean = false) => {
-		if (!opts.stateRoot) return;
-		const now = Date.now();
-		if (!force && (now - lastRegistryRefreshAt) < REGISTRY_REFRESH_INTERVAL_MS) return;
-		try {
-			const snapshot = buildRegistrySnapshot(opts.stateRoot, opts.batchId);
-			writeRegistrySnapshot(opts.stateRoot, snapshot);
-			lastRegistryRefreshAt = now;
-		} catch { /* best effort */ }
-	};
-
-	// Registry integration: write manifest before process is considered visible
-	if (opts.stateRoot) {
-		const manifest = createManifest({
-			batchId: opts.batchId,
-			agentId: opts.agentId,
-			role: opts.role,
-			laneNumber: opts.laneNumber,
-			taskId: opts.taskId,
-			repoId: opts.repoId,
-			pid: proc.pid ?? 0,
-			parentPid: process.pid,
-			cwd: opts.cwd,
-			packet: opts.packet ?? null,
-		});
-		manifest.status = "running";
-		writeManifest(opts.stateRoot, manifest);
-		refreshRegistrySnapshot(true);
-	}
-
-	// Helper: close stdin safely with delay
-	function closeStdin() {
-		if (stdinClosed) return;
-		stdinClosed = true;
-		if (closeDelayMs > 0) {
-			setTimeout(() => {
-				try { proc.stdin?.end(); } catch { /* ignore */ }
-			}, closeDelayMs);
-		} else {
-			try { proc.stdin?.end(); } catch { /* ignore */ }
-		}
-	}
-
-	// Helper: emit normalized event
-	function emitEvent(type: RuntimeAgentEventType, payload: Record<string, unknown> = {}) {
-		const event: RuntimeAgentEvent = {
-			batchId: opts.batchId,
-			agentId: opts.agentId,
-			role: opts.role,
-			laneNumber: opts.laneNumber,
-			taskId: opts.taskId,
-			repoId: opts.repoId,
-			ts: Date.now(),
-			type,
-			payload,
-		};
-		if (onEvent) onEvent(event);
-		// Persist to events JSONL if path is provided
-		if (opts.eventsPath) {
-			try {
-				mkdirSync(dirname(opts.eventsPath), { recursive: true });
-				appendFileSync(opts.eventsPath, JSON.stringify(event) + "\n", "utf-8");
-			} catch { /* best effort */ }
-		}
-	}
-
-	// Helper: check mailbox and inject (own inbox + _broadcast)
-	function checkMailbox() {
-		if (!opts.mailboxDir || !proc.stdin || proc.stdin.destroyed) return;
-
-		const expectedSessionName = basename(opts.mailboxDir);
-		const expectedBatchId = basename(dirname(opts.mailboxDir));
-
-		// Collect messages from own inbox AND broadcast inbox
-		const inboxDirs: Array<{ dir: string; isBroadcast: boolean }> = [
-			{ dir: join(opts.mailboxDir, "inbox"), isBroadcast: false },
-		];
-		// TP-106: Also check _broadcast/inbox for broadcast messages
-		const broadcastInbox = join(dirname(opts.mailboxDir), "_broadcast", "inbox");
-		if (existsSync(broadcastInbox)) {
-			inboxDirs.push({ dir: broadcastInbox, isBroadcast: true });
-		}
-
-		for (const { dir: inboxDir, isBroadcast } of inboxDirs) {
-			if (!existsSync(inboxDir)) continue;
-
-			let entries: string[];
-			try { entries = readdirSync(inboxDir); } catch { continue; }
-
-			const msgFiles = entries.filter(f => f.endsWith(".msg.json") && !f.endsWith(".msg.json.tmp")).sort();
-			if (msgFiles.length === 0) continue;
-
-			const ackDir = join(opts.mailboxDir, "ack");
-
-			for (const filename of msgFiles) {
-				try {
-					const raw = readFileSync(join(inboxDir, filename), "utf-8");
-					const msg = JSON.parse(raw);
-					if (!isValidMailboxMessage(msg)) continue;
-					if (msg.batchId !== expectedBatchId) continue;
-					// Validate 'to' field: own inbox requires exact match, broadcast accepts "_broadcast"
-					if (!isBroadcast && msg.to !== expectedSessionName) continue;
-					if (isBroadcast && msg.to !== "_broadcast") continue;
-
-					mkdirSync(ackDir, { recursive: true });
-					const ackPath = join(ackDir, filename);
-					// Broadcast fan-out: if this agent already acked this broadcast message,
-					// skip to avoid duplicate delivery while preserving message for peers.
-					if (isBroadcast && existsSync(ackPath)) continue;
-
-					proc.stdin.write(JSON.stringify({ type: "steer", message: msg.content }) + "\n");
-
-					if (isBroadcast) {
-						// Do NOT remove the shared broadcast inbox file. Persist a per-agent
-						// ack marker so all agents can consume the same broadcast exactly once.
-						try { writeFileSync(ackPath, raw, "utf-8"); } catch { /* best effort */ }
-					} else {
-						try { renameSync(join(inboxDir, filename), ackPath); } catch { /* race ok */ }
-					}
-
-					emitEvent("message_delivered", { messageId: msg.id, content: msg.content, broadcast: isBroadcast });
-					if (opts.stateRoot) {
-						appendMailboxAuditEvent(opts.stateRoot, expectedBatchId, {
-							type: "message_delivered",
-							from: msg.from,
-							to: isBroadcast ? expectedSessionName : msg.to,
-							messageId: msg.id,
-							messageType: msg.type,
-							contentPreview: msg.content.slice(0, 200),
-							broadcast: isBroadcast,
-						});
-					}
-
-					// TP-090: steering-pending flag
-					if (opts.steeringPendingPath) {
-						try {
-							appendFileSync(opts.steeringPendingPath,
-								JSON.stringify({ ts: msg.timestamp, content: msg.content, id: msg.id }) + "\n", "utf-8");
-						} catch { /* best effort */ }
-					}
-				} catch { /* skip malformed */ }
-			}
-		}
-	}
-
-	const promise = new Promise<AgentHostResult>((resolvePromise) => {
-		let stdoutBuf = "";
-		const decoder = new StringDecoder("utf8");
-		let finished = false;
-
-		function finish(exitCode: number | null, signal: string | null) {
-			if (finished) return;
-			finished = true;
-			if (timeoutHandle) clearTimeout(timeoutHandle);
-
-			const result: AgentHostResult = {
-				exitCode,
-				signal,
-				durationMs: Date.now() - startedAt,
-				killed,
-				inputTokens,
-				outputTokens,
-				cacheReadTokens,
-				cacheWriteTokens,
-				costUsd,
-				toolCalls,
-				lastTool,
-				retries,
-				compactions,
-				contextUsage,
-				error,
-				agentEnded,
-				stderrTail: stderrBuffer.trim().slice(-STDERR_MAX),
-			};
-
-			// Write exit summary if path provided
-			if (opts.exitSummaryPath) {
-				try {
-					mkdirSync(dirname(opts.exitSummaryPath), { recursive: true });
-					const summary = {
-						exitCode: result.exitCode,
-						exitSignal: result.signal,
-						tokens: (inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens) > 0
-							? { input: inputTokens, output: outputTokens, cacheRead: cacheReadTokens, cacheWrite: cacheWriteTokens }
-							: null,
-						cost: costUsd > 0 ? costUsd : null,
-						toolCalls,
-						retries,
-						compactions,
-						durationSec: Math.round(result.durationMs / 1000),
-						lastToolCall: lastTool || null,
-						error: error || null,
-						contextUsage: contextUsage || null,
-					};
-					writeFileSync(opts.exitSummaryPath, JSON.stringify(summary, null, 2) + "\n", "utf-8");
-				} catch { /* best effort */ }
-			}
-
-			const exitEventType: RuntimeAgentEventType =
-				timedOut ? "agent_timeout" :
-				killed ? "agent_killed" :
-				(exitCode === 0 && agentEnded) ? "agent_exited" :
-				"agent_crashed";
-			emitEvent(exitEventType, { exitCode, signal, durationMs: result.durationMs, timedOut });
-
-			// Registry integration: update manifest to terminal status
-			if (opts.stateRoot) {
-				const terminalStatus =
-					timedOut ? "timed_out" as const :
-					killed ? "killed" as const :
-					(exitCode === 0 && agentEnded) ? "exited" as const :
-					"crashed" as const;
-				updateManifestStatus(opts.stateRoot, opts.batchId, opts.agentId, terminalStatus);
-				refreshRegistrySnapshot(true);
-			}
-
-			resolvePromise(result);
-		}
-
-		proc.stdout.on("data", (chunk: Buffer | string) => {
-			stdoutBuf += typeof chunk === "string" ? chunk : decoder.write(chunk);
-			let idx: number;
-			while ((idx = stdoutBuf.indexOf("\n")) >= 0) {
-				let line = stdoutBuf.slice(0, idx);
-				stdoutBuf = stdoutBuf.slice(idx + 1);
-				if (line.endsWith("\r")) line = line.slice(0, -1);
-				if (!line.trim()) continue;
-
-				let event: any;
-				try { event = JSON.parse(line); } catch { continue; }
-				if (!event || !event.type) continue;
-
-				// Accumulate telemetry
-				switch (event.type) {
-					case "message_end": {
-						const usage = event.message?.usage;
-						if (usage) {
-							inputTokens += usage.input || 0;
-							outputTokens += usage.output || 0;
-							cacheReadTokens += usage.cacheRead || 0;
-							cacheWriteTokens += usage.cacheWrite || 0;
-							if (usage.cost) {
-								costUsd += typeof usage.cost === "object" ? (usage.cost.total || 0) : (typeof usage.cost === "number" ? usage.cost : 0);
-							}
-						}
-						// TP-111: Emit assistant_message with bounded content
-						if (event.message?.role === "assistant") {
-							const content = extractAssistantText(event.message);
-							if (content) {
-								emitEvent("assistant_message", { text: truncatePayload(content, MAX_CONV_PAYLOAD_CHARS) });
-								// TP-172: Track last assistant message for exit interception
-								lastAssistantMessage = content;
-							}
-						}
-						// Request session stats immediately on first assistant message,
-						// then periodically at a bounded cadence to refresh context usage.
-						if (event.message?.role === "assistant") {
-							assistantMessageEnds += 1;
-							if (assistantMessageEnds === 1 || assistantMessageEnds % STATS_REFRESH_EVERY_ASSISTANT_MESSAGES === 0) {
-								try { proc.stdin?.write(JSON.stringify({ type: "get_session_stats" }) + "\n"); } catch { /* ignore */ }
-							}
-						}
-						// Check mailbox
-						checkMailbox();
-						// Keep registry snapshot freshness while agent is active.
-						refreshRegistrySnapshot(false);
-						// Emit telemetry update
-						if (onTelemetry) {
-							onTelemetry({ inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, costUsd, toolCalls, lastTool, contextUsage });
-						}
-						break;
-					}
-					case "tool_execution_start": {
-						toolCalls++;
-						currentTurnHadToolCalls = true;
-						const toolName = event.toolName || "tool";
-						const argPreview = typeof event.args === "string" ? event.args.slice(0, 300) :
-							(event.args && typeof Object.values(event.args)[0] === "string" ? String(Object.values(event.args)[0]).slice(0, 300) : "");
-						lastTool = argPreview ? `${toolName}: ${argPreview}` : toolName;
-						// TP-111: Bounded payload only — no raw args in durable event log
-						const toolPath = event.args?.path ? String(event.args.path).slice(0, 200) : "";
-						emitEvent("tool_call", { tool: toolName, path: toolPath, argsPreview: argPreview });
-						break;
-					}
-					case "tool_execution_end": {
-						// TP-111: Include bounded result summary for dashboard display
-						const toolResultSummary = typeof event.result === "string" ? event.result.slice(0, 200)
-							: event.output ? String(event.output).slice(0, 200) : "";
-						emitEvent("tool_result", { tool: event.toolName, summary: toolResultSummary });
-						break;
-					}
-					case "auto_retry_start": {
-						retries++;
-						emitEvent("retry_started", { attempt: event.attempt, error: event.errorMessage || event.error });
-						break;
-					}
-					case "auto_compaction_start": {
-						compactions++;
-						emitEvent("compaction_started", {});
-						break;
-					}
-					case "response": {
-						if (event.success === false && event.error) {
-							error = event.error;
-						}
-						if (event.success === true && event.data?.contextUsage) {
-							contextUsage = event.data.contextUsage;
-							emitEvent("context_usage", { ...event.data.contextUsage });
-							// Emit telemetry immediately so context % is live in dashboard
-							if (onTelemetry) {
-								onTelemetry({ inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, costUsd, toolCalls, lastTool, contextUsage });
-							}
-						}
-						break;
-					}
-					case "agent_end": {
-						agentEnded = true;
-						// TP-172: Exit interception — intercept any exit when callback
-						// is provided and under limit. The callback (lane-runner) decides
-						// whether the worker made progress. We don't gate on tool calls
-						// because workers commonly use tools (reads/greps) then exit
-						// with a text declaration ("Now let me fix this:") without
-						// actually making the edit.
-						const shouldIntercept = opts.onPrematureExit
-							&& exitInterceptionCount < maxExitInterceptions;
-						if (shouldIntercept) {
-							exitInterceptionCount++;
-							const INTERCEPTION_TIMEOUT_MS = 120_000; // 2 minute safety timeout
-							// Wrap in Promise.resolve().then() to catch synchronous throws
-							const interceptPromise = Promise.resolve().then(() =>
-								opts.onPrematureExit!(lastAssistantMessage));
-							const timeoutPromise = new Promise<null>((res) =>
-								setTimeout(() => res(null), INTERCEPTION_TIMEOUT_MS));
-							Promise.race([interceptPromise, timeoutPromise])
-								.then(
-									(newPrompt: string | null) => {
-										if (newPrompt && !stdinClosed && proc.stdin && !proc.stdin.destroyed) {
-											// Re-prompt the agent with supervisor guidance
-											agentEnded = false; // Reset for the new turn
-											currentTurnHadToolCalls = false; // Reset for new turn
-											proc.stdin.write(JSON.stringify({ type: "prompt", message: newPrompt }) + "\n");
-											emitEvent("exit_intercepted", {
-												interceptionCount: exitInterceptionCount,
-												assistantMessage: truncatePayload(lastAssistantMessage, 500),
-												supervisorConsulted: true,
-												action: "reprompt",
-												newPromptPreview: truncatePayload(newPrompt, MAX_CONV_PAYLOAD_CHARS),
-											});
-										} else {
-											// Callback returned null or stdin already closed — close session
-											const reason = stdinClosed ? "stdin_closed"
-												: newPrompt === null ? "callback_returned_null"
-												: "unknown";
-											emitEvent("exit_intercepted", {
-												interceptionCount: exitInterceptionCount,
-												assistantMessage: truncatePayload(lastAssistantMessage, 500),
-												supervisorConsulted: true,
-												action: "close",
-												reason,
-											});
-											closeStdin();
-										}
-									},
-									(err: unknown) => {
-										// Callback rejected — emit single diagnostic event and close
-										const msg = err instanceof Error ? err.message : String(err);
-										emitEvent("exit_intercepted", {
-											interceptionCount: exitInterceptionCount,
-											assistantMessage: truncatePayload(lastAssistantMessage, 500),
-											supervisorConsulted: false,
-											action: "close",
-											reason: "callback_error",
-											error: msg,
-										});
-										closeStdin();
-									},
-								);
-						} else {
-							// No callback, had tool calls, or interception limit reached — close normally
-							if (opts.onPrematureExit && exitInterceptionCount >= maxExitInterceptions) {
-								emitEvent("exit_intercepted", {
-									interceptionCount: exitInterceptionCount,
-									assistantMessage: truncatePayload(lastAssistantMessage, 500),
-									supervisorConsulted: false,
-									action: "close",
-									reason: "max_interceptions_reached",
-								});
-							}
-							closeStdin();
-						}
-						break;
-					}
-				}
-			}
-		});
-
-		proc.stderr?.setEncoding("utf-8");
-		proc.stderr?.on("data", (chunk: string) => {
-			stderrBuffer += chunk;
-			if (stderrBuffer.length > STDERR_MAX * 2) {
-				stderrBuffer = stderrBuffer.slice(-STDERR_MAX);
-			}
-		});
-
-		proc.on("error", (err: Error) => {
-			error = `spawn error: ${err.message}`;
-			finish(null, null);
-		});
-
-		proc.on("close", (code: number | null, signal: string | null) => {
-			finish(code, signal);
-		});
-
-		// Send steering mode and prompt
-		if (opts.mailboxDir) {
-			proc.stdin.write(JSON.stringify({ type: "set_steering_mode", mode: "all" }) + "\n");
-		}
-		proc.stdin.write(JSON.stringify({ type: "prompt", message: opts.prompt }) + "\n");
-
-		emitEvent("agent_started", { model: opts.model, cwd: opts.cwd });
-		// TP-111: Emit prompt_sent with bounded preview
-		emitEvent("prompt_sent", { text: truncatePayload(opts.prompt, MAX_CONV_PAYLOAD_CHARS) });
-	});
-
-	const kill = () => {
-		killed = true;
-		try { proc.kill("SIGTERM"); } catch { /* ignore */ }
-	};
-
-	return { promise, kill };
-}
+/**
+ * Agent Host — Direct-child Pi agent hosting for Runtime V2
+ *
+ * Spawns `pi --mode rpc` as a direct child process (no terminal multiplexer, no shell),
+ * parses RPC JSONL events, normalizes them into RuntimeAgentEvents,
+ * manages mailbox delivery, and produces exit summaries.
+ *
+ * This replaces the legacy terminal-session hosting path with
+ * a programmatic parent-child model where the caller has full process
+ * ownership.
+ *
+ * Key differences from the legacy path:
+ *   1. No terminal-session backend — `spawn()` with `shell: false`
+ *   2. No sidecar tailing — events flow directly to the caller via callbacks
+ *   3. No PID-file orphan guessing — caller owns the process handle
+ *   4. Registry integration — manifests updated on status transitions
+ *   5. Pi CLI resolved to JS entrypoint, not .CMD shim
+ *
+ * @module taskplane/agent-host
+ * @since TP-104
+ */
+
+import { spawn, type ChildProcess } from "child_process";
+import {
+	readFileSync, writeFileSync, appendFileSync, mkdirSync,
+	existsSync, readdirSync, renameSync,
+} from "fs";
+import { join, dirname, basename, resolve } from "path";
+import { StringDecoder } from "string_decoder";
+
+import type {
+	RuntimeAgentId,
+	RuntimeAgentRole,
+	RuntimeAgentEvent,
+	RuntimeAgentEventType,
+	RuntimeAgentManifest,
+	PacketPaths,
+} from "./types.ts";
+
+import {
+	createManifest,
+	writeManifest,
+	updateManifestStatus,
+	buildRegistrySnapshot,
+	writeRegistrySnapshot,
+} from "./process-registry.ts";
+import { appendMailboxAuditEvent } from "./mailbox.ts";
+import { resolvePiCliPath } from "./path-resolver.ts";
+
+// ── Pi CLI Resolution ────────────────────────────────────────────────
+// resolvePiCliPath() is imported from path-resolver.ts and re-exported below (TP-157)
+
+export { resolvePiCliPath };
+
+// ── Worker Tools Allowlist (TP-184) ─────────────────────────────────
+
+/**
+ * Engine-internal tools that the orchestrator's bridge extension
+ * (`agent-bridge-extension.ts`) registers for every spawned worker. These
+ * tools are coordination primitives owned by taskplane, NOT user-facing
+ * capabilities, so they must be present in the worker's `--tools` allowlist
+ * regardless of what `taskRunner.worker.tools` is configured to.
+ *
+ * If a worker is spawned without one of these tools in its allowlist, pi's
+ * tool gate filters the registered tool out and the matching feature
+ * silently no-ops:
+ *   - `review_step`:                plan/code/test reviews never fire at
+ *                                   any Review Level >= 1
+ *   - `notify_supervisor`:          worker cannot reply to supervisor
+ *                                   steering messages
+ *   - `escalate_to_supervisor`:     worker cannot escalate blockers or
+ *                                   ambiguity to the supervisor/operator
+ *   - `request_segment_expansion`:  multi-repo segment expansion
+ *                                   unreachable (the request file IPC is
+ *                                   never written)
+ *
+ * Keep this list in sync with the registrations in
+ * `agent-bridge-extension.ts` (lines ~137, 180, 230, 599).
+ *
+ * @see https://github.com/HenryLach/taskplane/issues/530
+ * @since TP-184
+ */
+export const ENGINE_BRIDGE_TOOLS = [
+	"review_step",
+	"notify_supervisor",
+	"escalate_to_supervisor",
+	"request_segment_expansion",
+] as const;
+
+/**
+ * Default user-tools portion of the worker `--tools` allowlist. This is the
+ * fallback used when neither `taskRunner.worker.tools` config nor the
+ * `TASKPLANE_WORKER_TOOLS` env var supplies a value. Engine bridge tools
+ * (`ENGINE_BRIDGE_TOOLS`) are appended on top by
+ * `buildWorkerToolsAllowlist()` at the spawn site — they are NOT part of
+ * this default and should not be added by callers.
+ *
+ * NOTE: This literal is duplicated in `config-schema.ts` (defaults block)
+ * and `types.ts` (defaults block) as well. Those modules intentionally
+ * keep the literal to avoid pulling agent-host's heavy imports (child
+ * process, fs) into pure schema/type files. If you change the default
+ * here, update those copies too.
+ *
+ * @since TP-184
+ */
+export const DEFAULT_WORKER_USER_TOOLS = "read,write,edit,bash,grep,find,ls";
+
+/**
+ * Build the final worker `--tools` allowlist string by combining the
+ * user-tools portion (from config or {@link DEFAULT_WORKER_USER_TOOLS}) with
+ * {@link ENGINE_BRIDGE_TOOLS} (always appended, deduplicated).
+ *
+ * Semantics:
+ *   - `null` / `undefined` / empty / whitespace-only input → falls back to
+ *     {@link DEFAULT_WORKER_USER_TOOLS}
+ *   - Non-empty input → split on `,`, trim each entry, drop empties
+ *   - All three bridge tools are appended; duplicates are dropped via Set
+ *   - Returned string has no leading/trailing commas, no whitespace
+ *
+ * Call this exactly **once** in the spawn pipeline (currently
+ * `lane-runner.ts:580`) — augmentation is intended to be a single,
+ * idempotent layer; double-application is harmless (deduplicated) but
+ * obscures the data flow.
+ *
+ * @see https://github.com/HenryLach/taskplane/issues/530
+ * @since TP-184
+ */
+export function buildWorkerToolsAllowlist(userTools: string | undefined | null): string {
+	const userPart = (userTools && userTools.trim()) || DEFAULT_WORKER_USER_TOOLS;
+	const rawUserList = userPart.split(",").map((s) => s.trim()).filter(Boolean);
+	// Guard against delimiter-only / whitespace-only inputs (e.g. ",", " , ")
+	// that would otherwise parse to an empty list and yield bridge-tools-only
+	// workers with no file/shell capabilities.
+	const userList = rawUserList.length > 0
+		? rawUserList
+		: DEFAULT_WORKER_USER_TOOLS.split(",").map((s) => s.trim()).filter(Boolean);
+	const merged = new Set<string>(userList);
+	for (const t of ENGINE_BRIDGE_TOOLS) merged.add(t);
+	return Array.from(merged).join(",");
+}
+
+// ── Conversation Payload Helpers (TP-111) ───────────────────────────────
+
+/** Maximum characters for conversation event text payloads. */
+const MAX_CONV_PAYLOAD_CHARS = 2000;
+
+/** Truncate a string to maxLen chars, appending ellipsis if truncated. */
+function truncatePayload(text: string, maxLen: number): string {
+	if (text.length <= maxLen) return text;
+	return text.slice(0, maxLen) + "…";
+}
+
+/**
+ * Extract text content from a Pi RPC message_end event's message object.
+ * Pi may return content as a string or as an array of content blocks.
+ */
+function extractAssistantText(message: Record<string, unknown>): string {
+	// Direct string content
+	if (typeof message.content === "string") return message.content;
+	// Array of content blocks (Anthropic format)
+	// Guard: skip null/non-object entries to prevent TypeError on malformed streams
+	if (Array.isArray(message.content)) {
+		const textBlocks = message.content
+			.filter((b: unknown): b is { type: string; text: string } =>
+				typeof b === "object" && b !== null &&
+				(b as any).type === "text" && typeof (b as any).text === "string")
+			.map((b) => b.text);
+		if (textBlocks.length > 0) return textBlocks.join("\n");
+	}
+	// Fallback: try text field
+	if (typeof message.text === "string") return message.text;
+	return "";
+}
+
+// ── Types ────────────────────────────────────────────────────────────
+
+/**
+ * Options for spawning an agent via the direct host.
+ *
+ * @since TP-104
+ */
+export interface AgentHostOptions {
+	/** Stable agent identity */
+	agentId: RuntimeAgentId;
+	/** Agent role */
+	role: RuntimeAgentRole;
+	/** Batch ID this agent belongs to */
+	batchId: string;
+	/** Lane number (null for merge agents) */
+	laneNumber: number | null;
+	/** Task ID being executed (null before first assignment) */
+	taskId: string | null;
+	/** Repo ID the agent is operating in */
+	repoId: string;
+	/** Working directory for the Pi process */
+	cwd: string;
+	/** User prompt content */
+	prompt: string;
+	/** Optional system prompt content */
+	systemPrompt?: string;
+	/** Model identifier (e.g., "anthropic/claude-sonnet-4-20250514") */
+	model?: string;
+	/** Comma-separated tool list */
+	tools?: string;
+	/** Thinking mode override */
+	thinking?: string;
+	/** Extension paths to load */
+	extensions?: string[];
+	/** Mailbox directory for steering (null = no mailbox) */
+	mailboxDir?: string | null;
+	/** Steering-pending JSONL path (TP-090, worker-only) */
+	steeringPendingPath?: string | null;
+	/** Path to persist normalized events JSONL */
+	eventsPath?: string | null;
+	/** Path to write exit summary JSON */
+	exitSummaryPath?: string | null;
+	/** Timeout in milliseconds (0 = no timeout) */
+	timeoutMs?: number;
+	/** Delay in ms before closing stdin after agent_end (default: 100) */
+	closeDelayMs?: number;
+	/** State root for process registry (null = no registry integration) */
+	stateRoot?: string | null;
+	/** Packet paths for registry manifest (null for merge agents) */
+	packet?: PacketPaths | null;
+	/** Extra environment variables for the child process */
+	env?: Record<string, string>;
+	/**
+	 * Callback invoked when agent_end fires, before stdin is closed.
+	 * Receives the last assistant message text.
+	 * Return a string to send as a new prompt (re-prompt the agent),
+	 * or null to close the session normally.
+	 *
+	 * @since TP-172
+	 */
+	onPrematureExit?: (assistantMessage: string) => Promise<string | null>;
+	/**
+	 * Maximum number of exit interceptions before forcing session close.
+	 * Prevents infinite loops where the callback always returns a new prompt.
+	 * Default: 2
+	 *
+	 * @since TP-172
+	 */
+	maxExitInterceptions?: number;
+}
+
+/**
+ * Accumulated telemetry from a completed agent session.
+ *
+ * @since TP-104
+ */
+export interface AgentHostResult {
+	/** Process exit code (null if killed by signal) */
+	exitCode: number | null;
+	/** Signal that killed the process (null if exited normally) */
+	signal: string | null;
+	/** Wall-clock duration in milliseconds */
+	durationMs: number;
+	/** Whether the process was killed by the caller */
+	killed: boolean;
+	/** Total input tokens */
+	inputTokens: number;
+	/** Total output tokens */
+	outputTokens: number;
+	/** Cache read tokens */
+	cacheReadTokens: number;
+	/** Cache write tokens */
+	cacheWriteTokens: number;
+	/** Cumulative cost in USD */
+	costUsd: number;
+	/** Number of tool calls */
+	toolCalls: number;
+	/** Last tool call description */
+	lastTool: string;
+	/** Number of auto-retries */
+	retries: number;
+	/** Number of auto-compactions */
+	compactions: number;
+	/** Authoritative context usage from Pi */
+	contextUsage: { tokens: number; contextWindow: number; percent: number } | null;
+	/** Final error message (null if clean exit) */
+	error: string | null;
+	/** Whether agent_end was received */
+	agentEnded: boolean;
+	/** Captured stderr tail (last 2KB) */
+	stderrTail: string;
+}
+
+/**
+ * Callback for normalized agent events.
+ *
+ * @since TP-104
+ */
+export type AgentEventCallback = (event: RuntimeAgentEvent) => void;
+
+/**
+ * Callback for telemetry updates (called on each message_end).
+ *
+ * @since TP-104
+ */
+export type AgentTelemetryCallback = (result: Partial<AgentHostResult>) => void;
+
+// ── JSONL Helpers ────────────────────────────────────────────────────
+
+const MAILBOX_MESSAGE_TYPES = new Set(["steer", "query", "abort", "info", "reply", "escalate"]);
+
+function isValidMailboxMessage(obj: any): boolean {
+	if (!obj || typeof obj !== "object") return false;
+	return (
+		typeof obj.id === "string" &&
+		typeof obj.batchId === "string" &&
+		typeof obj.from === "string" &&
+		typeof obj.to === "string" &&
+		typeof obj.timestamp === "number" && Number.isFinite(obj.timestamp) &&
+		typeof obj.type === "string" && MAILBOX_MESSAGE_TYPES.has(obj.type) &&
+		typeof obj.content === "string"
+	);
+}
+
+// ── Core Host Function ───────────────────────────────────────────────
+
+/**
+ * Spawn and manage a Pi agent as a direct child process.
+ *
+ * Returns a promise that resolves with the full session result when
+ * the agent exits, plus a kill function for early termination.
+ *
+ * @param opts - Agent host options
+ * @param onEvent - Optional callback for normalized events
+ * @param onTelemetry - Optional callback for telemetry updates
+ * @returns Object with promise (resolves on exit) and kill function
+ *
+ * @since TP-104
+ */
+export function spawnAgent(
+	opts: AgentHostOptions,
+	onEvent?: AgentEventCallback,
+	onTelemetry?: AgentTelemetryCallback,
+): { promise: Promise<AgentHostResult>; kill: () => void } {
+
+	const cliPath = resolvePiCliPath();
+	const closeDelayMs = opts.closeDelayMs ?? 100;
+	const timeoutMs = opts.timeoutMs ?? 0;
+	const maxExitInterceptions = opts.maxExitInterceptions ?? 3;
+
+	// Build Pi CLI arguments
+	const piArgs: string[] = [cliPath, "--mode", "rpc", "--no-session"];
+	if (opts.model) piArgs.push("--model", opts.model);
+	if (opts.tools) piArgs.push("--tools", opts.tools);
+	if (opts.systemPrompt) piArgs.push("--system-prompt", opts.systemPrompt);
+	// Always pass --no-extensions to prevent auto-discovery from cwd.
+	// Explicit -e entries are still honored by pi even with --no-extensions.
+	// This matches the fix from TP-095 that eliminated duplicate extension loading.
+	piArgs.push("--no-extensions");
+	if (opts.extensions && opts.extensions.length > 0) {
+		for (const ext of opts.extensions) {
+			piArgs.push("-e", ext);
+		}
+	}
+	piArgs.push("--no-skills");
+	if (opts.thinking) piArgs.push("--thinking", opts.thinking);
+
+	// Spawn directly — no shell, no terminal multiplexer
+	const proc = spawn(process.execPath, piArgs, {
+		shell: false,
+		cwd: opts.cwd,
+		stdio: ["pipe", "pipe", "pipe"],
+		env: { ...process.env, ...(opts.env ?? {}) },
+	});
+
+	// State accumulator
+	const startedAt = Date.now();
+	let killed = false;
+	let timedOut = false;
+	let agentEnded = false;
+	let stdinClosed = false;
+	let assistantMessageEnds = 0;
+	const STATS_REFRESH_EVERY_ASSISTANT_MESSAGES = 5;
+	let inputTokens = 0, outputTokens = 0, cacheReadTokens = 0, cacheWriteTokens = 0;
+	let costUsd = 0, toolCalls = 0, retries = 0, compactions = 0;
+	let lastTool = "", error: string | null = null;
+	let contextUsage: AgentHostResult["contextUsage"] = null;
+	let stderrBuffer = "";
+	const STDERR_MAX = 2048;
+	/** Last assistant message text captured from message_end events (TP-172) */
+	let lastAssistantMessage = "";
+	/** Number of times exit interception has occurred (TP-172) */
+	let exitInterceptionCount = 0;
+	/** Whether the current turn had any tool calls (TP-172: text-only gate) */
+	let currentTurnHadToolCalls = false;
+
+	// Timeout
+	let timeoutHandle: ReturnType<typeof setTimeout> | null = null;
+	if (timeoutMs > 0) {
+		timeoutHandle = setTimeout(() => {
+			timedOut = true;
+			killed = true;
+			try { proc.kill("SIGTERM"); } catch { /* ignore */ }
+		}, timeoutMs);
+	}
+
+	const REGISTRY_REFRESH_INTERVAL_MS = 1_000;
+	let lastRegistryRefreshAt = 0;
+	const refreshRegistrySnapshot = (force: boolean = false) => {
+		if (!opts.stateRoot) return;
+		const now = Date.now();
+		if (!force && (now - lastRegistryRefreshAt) < REGISTRY_REFRESH_INTERVAL_MS) return;
+		try {
+			const snapshot = buildRegistrySnapshot(opts.stateRoot, opts.batchId);
+			writeRegistrySnapshot(opts.stateRoot, snapshot);
+			lastRegistryRefreshAt = now;
+		} catch { /* best effort */ }
+	};
+
+	// Registry integration: write manifest before process is considered visible
+	if (opts.stateRoot) {
+		const manifest = createManifest({
+			batchId: opts.batchId,
+			agentId: opts.agentId,
+			role: opts.role,
+			laneNumber: opts.laneNumber,
+			taskId: opts.taskId,
+			repoId: opts.repoId,
+			pid: proc.pid ?? 0,
+			parentPid: process.pid,
+			cwd: opts.cwd,
+			packet: opts.packet ?? null,
+		});
+		manifest.status = "running";
+		writeManifest(opts.stateRoot, manifest);
+		refreshRegistrySnapshot(true);
+	}
+
+	// Helper: close stdin safely with delay
+	function closeStdin() {
+		if (stdinClosed) return;
+		stdinClosed = true;
+		if (closeDelayMs > 0) {
+			setTimeout(() => {
+				try { proc.stdin?.end(); } catch { /* ignore */ }
+			}, closeDelayMs);
+		} else {
+			try { proc.stdin?.end(); } catch { /* ignore */ }
+		}
+	}
+
+	// Helper: emit normalized event
+	function emitEvent(type: RuntimeAgentEventType, payload: Record<string, unknown> = {}) {
+		const event: RuntimeAgentEvent = {
+			batchId: opts.batchId,
+			agentId: opts.agentId,
+			role: opts.role,
+			laneNumber: opts.laneNumber,
+			taskId: opts.taskId,
+			repoId: opts.repoId,
+			ts: Date.now(),
+			type,
+			payload,
+		};
+		if (onEvent) onEvent(event);
+		// Persist to events JSONL if path is provided
+		if (opts.eventsPath) {
+			try {
+				mkdirSync(dirname(opts.eventsPath), { recursive: true });
+				appendFileSync(opts.eventsPath, JSON.stringify(event) + "\n", "utf-8");
+			} catch { /* best effort */ }
+		}
+	}
+
+	// Helper: check mailbox and inject (own inbox + _broadcast)
+	function checkMailbox() {
+		if (!opts.mailboxDir || !proc.stdin || proc.stdin.destroyed) return;
+
+		const expectedSessionName = basename(opts.mailboxDir);
+		const expectedBatchId = basename(dirname(opts.mailboxDir));
+
+		// Collect messages from own inbox AND broadcast inbox
+		const inboxDirs: Array<{ dir: string; isBroadcast: boolean }> = [
+			{ dir: join(opts.mailboxDir, "inbox"), isBroadcast: false },
+		];
+		// TP-106: Also check _broadcast/inbox for broadcast messages
+		const broadcastInbox = join(dirname(opts.mailboxDir), "_broadcast", "inbox");
+		if (existsSync(broadcastInbox)) {
+			inboxDirs.push({ dir: broadcastInbox, isBroadcast: true });
+		}
+
+		for (const { dir: inboxDir, isBroadcast } of inboxDirs) {
+			if (!existsSync(inboxDir)) continue;
+
+			let entries: string[];
+			try { entries = readdirSync(inboxDir); } catch { continue; }
+
+			const msgFiles = entries.filter(f => f.endsWith(".msg.json") && !f.endsWith(".msg.json.tmp")).sort();
+			if (msgFiles.length === 0) continue;
+
+			const ackDir = join(opts.mailboxDir, "ack");
+
+			for (const filename of msgFiles) {
+				try {
+					const raw = readFileSync(join(inboxDir, filename), "utf-8");
+					const msg = JSON.parse(raw);
+					if (!isValidMailboxMessage(msg)) continue;
+					if (msg.batchId !== expectedBatchId) continue;
+					// Validate 'to' field: own inbox requires exact match, broadcast accepts "_broadcast"
+					if (!isBroadcast && msg.to !== expectedSessionName) continue;
+					if (isBroadcast && msg.to !== "_broadcast") continue;
+
+					mkdirSync(ackDir, { recursive: true });
+					const ackPath = join(ackDir, filename);
+					// Broadcast fan-out: if this agent already acked this broadcast message,
+					// skip to avoid duplicate delivery while preserving message for peers.
+					if (isBroadcast && existsSync(ackPath)) continue;
+
+					proc.stdin.write(JSON.stringify({ type: "steer", message: msg.content }) + "\n");
+
+					if (isBroadcast) {
+						// Do NOT remove the shared broadcast inbox file. Persist a per-agent
+						// ack marker so all agents can consume the same broadcast exactly once.
+						try { writeFileSync(ackPath, raw, "utf-8"); } catch { /* best effort */ }
+					} else {
+						try { renameSync(join(inboxDir, filename), ackPath); } catch { /* race ok */ }
+					}
+
+					emitEvent("message_delivered", { messageId: msg.id, content: msg.content, broadcast: isBroadcast });
+					if (opts.stateRoot) {
+						appendMailboxAuditEvent(opts.stateRoot, expectedBatchId, {
+							type: "message_delivered",
+							from: msg.from,
+							to: isBroadcast ? expectedSessionName : msg.to,
+							messageId: msg.id,
+							messageType: msg.type,
+							contentPreview: msg.content.slice(0, 200),
+							broadcast: isBroadcast,
+						});
+					}
+
+					// TP-090: steering-pending flag
+					if (opts.steeringPendingPath) {
+						try {
+							appendFileSync(opts.steeringPendingPath,
+								JSON.stringify({ ts: msg.timestamp, content: msg.content, id: msg.id }) + "\n", "utf-8");
+						} catch { /* best effort */ }
+					}
+				} catch { /* skip malformed */ }
+			}
+		}
+	}
+
+	const promise = new Promise<AgentHostResult>((resolvePromise) => {
+		let stdoutBuf = "";
+		const decoder = new StringDecoder("utf8");
+		let finished = false;
+
+		function finish(exitCode: number | null, signal: string | null) {
+			if (finished) return;
+			finished = true;
+			if (timeoutHandle) clearTimeout(timeoutHandle);
+
+			const result: AgentHostResult = {
+				exitCode,
+				signal,
+				durationMs: Date.now() - startedAt,
+				killed,
+				inputTokens,
+				outputTokens,
+				cacheReadTokens,
+				cacheWriteTokens,
+				costUsd,
+				toolCalls,
+				lastTool,
+				retries,
+				compactions,
+				contextUsage,
+				error,
+				agentEnded,
+				stderrTail: stderrBuffer.trim().slice(-STDERR_MAX),
+			};
+
+			// Write exit summary if path provided
+			if (opts.exitSummaryPath) {
+				try {
+					mkdirSync(dirname(opts.exitSummaryPath), { recursive: true });
+					const summary = {
+						exitCode: result.exitCode,
+						exitSignal: result.signal,
+						tokens: (inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens) > 0
+							? { input: inputTokens, output: outputTokens, cacheRead: cacheReadTokens, cacheWrite: cacheWriteTokens }
+							: null,
+						cost: costUsd > 0 ? costUsd : null,
+						toolCalls,
+						retries,
+						compactions,
+						durationSec: Math.round(result.durationMs / 1000),
+						lastToolCall: lastTool || null,
+						error: error || null,
+						contextUsage: contextUsage || null,
+					};
+					writeFileSync(opts.exitSummaryPath, JSON.stringify(summary, null, 2) + "\n", "utf-8");
+				} catch { /* best effort */ }
+			}
+
+			const exitEventType: RuntimeAgentEventType =
+				timedOut ? "agent_timeout" :
+				killed ? "agent_killed" :
+				(exitCode === 0 && agentEnded) ? "agent_exited" :
+				"agent_crashed";
+			emitEvent(exitEventType, { exitCode, signal, durationMs: result.durationMs, timedOut });
+
+			// Registry integration: update manifest to terminal status
+			if (opts.stateRoot) {
+				const terminalStatus =
+					timedOut ? "timed_out" as const :
+					killed ? "killed" as const :
+					(exitCode === 0 && agentEnded) ? "exited" as const :
+					"crashed" as const;
+				updateManifestStatus(opts.stateRoot, opts.batchId, opts.agentId, terminalStatus);
+				refreshRegistrySnapshot(true);
+			}
+
+			resolvePromise(result);
+		}
+
+		proc.stdout.on("data", (chunk: Buffer | string) => {
+			stdoutBuf += typeof chunk === "string" ? chunk : decoder.write(chunk);
+			let idx: number;
+			while ((idx = stdoutBuf.indexOf("\n")) >= 0) {
+				let line = stdoutBuf.slice(0, idx);
+				stdoutBuf = stdoutBuf.slice(idx + 1);
+				if (line.endsWith("\r")) line = line.slice(0, -1);
+				if (!line.trim()) continue;
+
+				let event: any;
+				try { event = JSON.parse(line); } catch { continue; }
+				if (!event || !event.type) continue;
+
+				// Accumulate telemetry
+				switch (event.type) {
+					case "message_end": {
+						const usage = event.message?.usage;
+						if (usage) {
+							inputTokens += usage.input || 0;
+							outputTokens += usage.output || 0;
+							cacheReadTokens += usage.cacheRead || 0;
+							cacheWriteTokens += usage.cacheWrite || 0;
+							if (usage.cost) {
+								costUsd += typeof usage.cost === "object" ? (usage.cost.total || 0) : (typeof usage.cost === "number" ? usage.cost : 0);
+							}
+						}
+						// TP-111: Emit assistant_message with bounded content
+						if (event.message?.role === "assistant") {
+							const content = extractAssistantText(event.message);
+							if (content) {
+								emitEvent("assistant_message", { text: truncatePayload(content, MAX_CONV_PAYLOAD_CHARS) });
+								// TP-172: Track last assistant message for exit interception
+								lastAssistantMessage = content;
+							}
+						}
+						// Request session stats immediately on first assistant message,
+						// then periodically at a bounded cadence to refresh context usage.
+						if (event.message?.role === "assistant") {
+							assistantMessageEnds += 1;
+							if (assistantMessageEnds === 1 || assistantMessageEnds % STATS_REFRESH_EVERY_ASSISTANT_MESSAGES === 0) {
+								try { proc.stdin?.write(JSON.stringify({ type: "get_session_stats" }) + "\n"); } catch { /* ignore */ }
+							}
+						}
+						// Check mailbox
+						checkMailbox();
+						// Keep registry snapshot freshness while agent is active.
+						refreshRegistrySnapshot(false);
+						// Emit telemetry update
+						if (onTelemetry) {
+							onTelemetry({ inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, costUsd, toolCalls, lastTool, contextUsage });
+						}
+						break;
+					}
+					case "tool_execution_start": {
+						toolCalls++;
+						currentTurnHadToolCalls = true;
+						const toolName = event.toolName || "tool";
+						const argPreview = typeof event.args === "string" ? event.args.slice(0, 300) :
+							(event.args && typeof Object.values(event.args)[0] === "string" ? String(Object.values(event.args)[0]).slice(0, 300) : "");
+						lastTool = argPreview ? `${toolName}: ${argPreview}` : toolName;
+						// TP-111: Bounded payload only — no raw args in durable event log
+						const toolPath = event.args?.path ? String(event.args.path).slice(0, 200) : "";
+						emitEvent("tool_call", { tool: toolName, path: toolPath, argsPreview: argPreview });
+						break;
+					}
+					case "tool_execution_end": {
+						// TP-111: Include bounded result summary for dashboard display
+						const toolResultSummary = typeof event.result === "string" ? event.result.slice(0, 200)
+							: event.output ? String(event.output).slice(0, 200) : "";
+						emitEvent("tool_result", { tool: event.toolName, summary: toolResultSummary });
+						break;
+					}
+					case "auto_retry_start": {
+						retries++;
+						emitEvent("retry_started", { attempt: event.attempt, error: event.errorMessage || event.error });
+						break;
+					}
+					case "auto_compaction_start": {
+						compactions++;
+						emitEvent("compaction_started", {});
+						break;
+					}
+					case "response": {
+						if (event.success === false && event.error) {
+							error = event.error;
+						}
+						if (event.success === true && event.data?.contextUsage) {
+							contextUsage = event.data.contextUsage;
+							emitEvent("context_usage", { ...event.data.contextUsage });
+							// Emit telemetry immediately so context % is live in dashboard
+							if (onTelemetry) {
+								onTelemetry({ inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, costUsd, toolCalls, lastTool, contextUsage });
+							}
+						}
+						break;
+					}
+					case "agent_end": {
+						agentEnded = true;
+						// TP-172: Exit interception — intercept any exit when callback
+						// is provided and under limit. The callback (lane-runner) decides
+						// whether the worker made progress. We don't gate on tool calls
+						// because workers commonly use tools (reads/greps) then exit
+						// with a text declaration ("Now let me fix this:") without
+						// actually making the edit.
+						const shouldIntercept = opts.onPrematureExit
+							&& exitInterceptionCount < maxExitInterceptions;
+						if (shouldIntercept) {
+							exitInterceptionCount++;
+							const INTERCEPTION_TIMEOUT_MS = 120_000; // 2 minute safety timeout
+							// Wrap in Promise.resolve().then() to catch synchronous throws
+							const interceptPromise = Promise.resolve().then(() =>
+								opts.onPrematureExit!(lastAssistantMessage));
+							const timeoutPromise = new Promise<null>((res) =>
+								setTimeout(() => res(null), INTERCEPTION_TIMEOUT_MS));
+							Promise.race([interceptPromise, timeoutPromise])
+								.then(
+									(newPrompt: string | null) => {
+										if (newPrompt && !stdinClosed && proc.stdin && !proc.stdin.destroyed) {
+											// Re-prompt the agent with supervisor guidance
+											agentEnded = false; // Reset for the new turn
+											currentTurnHadToolCalls = false; // Reset for new turn
+											proc.stdin.write(JSON.stringify({ type: "prompt", message: newPrompt }) + "\n");
+											emitEvent("exit_intercepted", {
+												interceptionCount: exitInterceptionCount,
+												assistantMessage: truncatePayload(lastAssistantMessage, 500),
+												supervisorConsulted: true,
+												action: "reprompt",
+												newPromptPreview: truncatePayload(newPrompt, MAX_CONV_PAYLOAD_CHARS),
+											});
+										} else {
+											// Callback returned null or stdin already closed — close session
+											const reason = stdinClosed ? "stdin_closed"
+												: newPrompt === null ? "callback_returned_null"
+												: "unknown";
+											emitEvent("exit_intercepted", {
+												interceptionCount: exitInterceptionCount,
+												assistantMessage: truncatePayload(lastAssistantMessage, 500),
+												supervisorConsulted: true,
+												action: "close",
+												reason,
+											});
+											closeStdin();
+										}
+									},
+									(err: unknown) => {
+										// Callback rejected — emit single diagnostic event and close
+										const msg = err instanceof Error ? err.message : String(err);
+										emitEvent("exit_intercepted", {
+											interceptionCount: exitInterceptionCount,
+											assistantMessage: truncatePayload(lastAssistantMessage, 500),
+											supervisorConsulted: false,
+											action: "close",
+											reason: "callback_error",
+											error: msg,
+										});
+										closeStdin();
+									},
+								);
+						} else {
+							// No callback, had tool calls, or interception limit reached — close normally
+							if (opts.onPrematureExit && exitInterceptionCount >= maxExitInterceptions) {
+								emitEvent("exit_intercepted", {
+									interceptionCount: exitInterceptionCount,
+									assistantMessage: truncatePayload(lastAssistantMessage, 500),
+									supervisorConsulted: false,
+									action: "close",
+									reason: "max_interceptions_reached",
+								});
+							}
+							closeStdin();
+						}
+						break;
+					}
+				}
+			}
+		});
+
+		proc.stderr?.setEncoding("utf-8");
+		proc.stderr?.on("data", (chunk: string) => {
+			stderrBuffer += chunk;
+			if (stderrBuffer.length > STDERR_MAX * 2) {
+				stderrBuffer = stderrBuffer.slice(-STDERR_MAX);
+			}
+		});
+
+		proc.on("error", (err: Error) => {
+			error = `spawn error: ${err.message}`;
+			finish(null, null);
+		});
+
+		proc.on("close", (code: number | null, signal: string | null) => {
+			finish(code, signal);
+		});
+
+		// Send steering mode and prompt
+		if (opts.mailboxDir) {
+			proc.stdin.write(JSON.stringify({ type: "set_steering_mode", mode: "all" }) + "\n");
+		}
+		proc.stdin.write(JSON.stringify({ type: "prompt", message: opts.prompt }) + "\n");
+
+		emitEvent("agent_started", { model: opts.model, cwd: opts.cwd });
+		// TP-111: Emit prompt_sent with bounded preview
+		emitEvent("prompt_sent", { text: truncatePayload(opts.prompt, MAX_CONV_PAYLOAD_CHARS) });
+	});
+
+	const kill = () => {
+		killed = true;
+		try { proc.kill("SIGTERM"); } catch { /* ignore */ }
+	};
+
+	return { promise, kill };
+}