taskplane 0.22.10 → 0.22.12

package/bin/rpc-wrapper.mjs

@@ -28,8 +28,8 @@
  */
 
 import { spawn } from "node:child_process";
-import { readFileSync, writeFileSync, appendFileSync, mkdirSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { readFileSync, writeFileSync, appendFileSync, mkdirSync, readdirSync, renameSync } from "node:fs";
+import { dirname, resolve, join, basename } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 
 // ── CLI Argument Parsing ─────────────────────────────────────────────
@@ -45,6 +45,7 @@ function parseArgs(argv) {
 		extensions: [],
 		passthrough: [],
 		help: false,
+		mailboxDir: null,
 	};
 
 	let i = 2; // skip "node" and script path
@@ -74,6 +75,9 @@ function parseArgs(argv) {
 		} else if (arg === "--extensions" && i + 1 < argv.length) {
 			args.extensions = argv[++i].split(",").map((e) => e.trim()).filter(Boolean);
 			i++;
+		} else if (arg === "--mailbox-dir" && i + 1 < argv.length) {
+			args.mailboxDir = argv[++i];
+			i++;
 		} else if (arg === "--") {
 			args.passthrough = argv.slice(i + 1);
 			break;
@@ -103,6 +107,7 @@ Optional:
   --system-prompt-file <path>  Path to system prompt file
   --tools <t1,t2,...>          Comma-separated tool names
   --extensions <e1,e2,...>     Comma-separated extension paths
+  --mailbox-dir <path>         Mailbox directory for agent steering (TP-089)
   -h, --help                   Show this help
 `
 	);
@@ -487,6 +492,160 @@ function createSingleWriteGuard(writer) {
 	};
 }
 
+// ── Agent Mailbox Check (TP-089) ─────────────────────────────────────
+
+/**
+ * Valid mailbox message types (must match MailboxMessageType in types.ts).
+ */
+const MAILBOX_MESSAGE_TYPES = new Set(["steer", "query", "abort", "info", "reply", "escalate"]);
+
+/**
+ * Check the agent's mailbox inbox for pending messages and inject them
+ * into the pi process via the `steer` RPC command.
+ *
+ * Called on every `message_end` event when `--mailbox-dir` is provided.
+ * Messages are validated (batchId, to, shape), sorted deterministically,
+ * injected via steer, and moved from inbox/ to ack/.
+ *
+ * @param {string} mailboxDir - Session mailbox directory (e.g., .pi/mailbox/{batchId}/{session})
+ * @param {object} proc - The spawned pi process (must have writable stdin)
+ * @returns {{ delivered: number, skipped: number }} Delivery stats
+ */
+function checkMailboxAndSteer(mailboxDir, proc) {
+	const stats = { delivered: 0, skipped: 0 };
+
+	// Derive expected values from path structure:
+	// mailboxDir = .pi/mailbox/{batchId}/{sessionName}
+	const expectedSessionName = basename(mailboxDir);
+	const expectedBatchId = basename(dirname(mailboxDir));
+
+	const inboxDir = join(mailboxDir, "inbox");
+
+	// Read inbox — ENOENT is quiet no-op (inbox may not exist yet)
+	let entries;
+	try {
+		entries = readdirSync(inboxDir);
+	} catch (err) {
+		if (err.code === "ENOENT") return stats;
+		process.stderr.write(`\n[STEERING] WARNING: failed to read inbox: ${err.message}\n`);
+		return stats;
+	}
+
+	// Filter: only *.msg.json files (excludes .msg.json.tmp temp files)
+	const msgFiles = entries.filter(f => f.endsWith(".msg.json") && !f.endsWith(".msg.json.tmp"));
+	if (msgFiles.length === 0) return stats;
+
+	// Read and validate all messages
+	const validMessages = [];
+
+	for (const filename of msgFiles) {
+		const filePath = join(inboxDir, filename);
+		let raw;
+		try {
+			raw = readFileSync(filePath, "utf-8");
+		} catch (err) {
+			process.stderr.write(`\n[STEERING] WARNING: failed to read ${filename}: ${err.message}\n`);
+			stats.skipped++;
+			continue;
+		}
+
+		let msg;
+		try {
+			msg = JSON.parse(raw);
+		} catch {
+			process.stderr.write(`\n[STEERING] WARNING: malformed JSON in ${filename}, skipping\n`);
+			stats.skipped++;
+			continue;
+		}
+
+		// Validate shape
+		if (!isValidMailboxMessageShape(msg)) {
+			process.stderr.write(`\n[STEERING] WARNING: invalid message shape in ${filename}, skipping\n`);
+			stats.skipped++;
+			continue;
+		}
+
+		// Validate batchId (derived from path, not message content)
+		if (msg.batchId !== expectedBatchId) {
+			process.stderr.write(`\n[STEERING] WARNING: batchId mismatch in ${filename} (expected ${expectedBatchId}, got ${msg.batchId}), skipping\n`);
+			stats.skipped++;
+			continue;
+		}
+
+		// Validate to (no misdelivery)
+		if (msg.to !== expectedSessionName) {
+			process.stderr.write(`\n[STEERING] WARNING: misdelivery in ${filename} (to=${msg.to}, expected ${expectedSessionName}), skipping\n`);
+			stats.skipped++;
+			continue;
+		}
+
+		validMessages.push({ filename, message: msg });
+	}
+
+	// Sort: primary by timestamp ascending, tie-break by filename lexical
+	validMessages.sort((a, b) => {
+		const tsDiff = a.message.timestamp - b.message.timestamp;
+		if (tsDiff !== 0) return tsDiff;
+		return a.filename.localeCompare(b.filename);
+	});
+
+	// Inject each message via steer RPC command and move to ack/
+	for (const { filename, message } of validMessages) {
+		try {
+			// Precondition: stdin must be available for injection.
+			// If stdin is closed/destroyed, keep message in inbox (no false ack).
+			if (!proc.stdin || proc.stdin.destroyed) {
+				stats.skipped++;
+				continue;
+			}
+
+			// Inject via steer RPC command
+			proc.stdin.write(JSON.stringify({ type: "steer", message: message.content }) + "\n");
+
+			// Move to ack/ (delivery proof)
+			const ackDir = join(mailboxDir, "ack");
+			try { mkdirSync(ackDir, { recursive: true }); } catch { /* exists */ }
+			try {
+				renameSync(join(inboxDir, filename), join(ackDir, filename));
+			} catch (err) {
+				// ENOENT race is harmless (another process acked it)
+				if (err.code !== "ENOENT") {
+					process.stderr.write(`\n[STEERING] WARNING: failed to ack ${filename}: ${err.message}\n`);
+				}
+			}
+
+			stats.delivered++;
+			process.stderr.write(`\n[STEERING] Delivered message ${message.id}\n`);
+		} catch (err) {
+			process.stderr.write(`\n[STEERING] WARNING: failed to deliver ${filename}: ${err.message}\n`);
+			stats.skipped++;
+		}
+	}
+
+	return stats;
+}
+
+/**
+ * Runtime validation for mailbox message shape in rpc-wrapper.
+ * Mirrors isValidMailboxMessage() from mailbox.ts but as a standalone
+ * function (rpc-wrapper.mjs is a plain .mjs module, not TypeScript).
+ *
+ * @param {any} obj - Parsed JSON value
+ * @returns {boolean} true if valid shape
+ */
+function isValidMailboxMessageShape(obj) {
+	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"
+	);
+}
+
 // ── Exports for Testing ──────────────────────────────────────────────
 
 // Export pure functions so tests can import them without triggering side effects.
@@ -503,6 +662,9 @@ export {
 	applyEvent,
 	buildExitSummary,
 	createSingleWriteGuard,
+	checkMailboxAndSteer,
+	isValidMailboxMessageShape,
+	MAILBOX_MESSAGE_TYPES,
 };
 
 // ── Main ─────────────────────────────────────────────────────────────
@@ -602,6 +764,15 @@ const proc = spawn("pi", piArgs, {
 const promptCmd = { type: "prompt", message: promptContent };
 proc.stdin.write(JSON.stringify(promptCmd) + "\n");
 
+// ── Agent Mailbox Steering Setup (TP-089) ────────────────────────────
+// When mailbox-dir is provided, set steering mode to "all" so queued
+// steering messages are delivered together at the next turn boundary.
+// Must be sent after prompt but before any agent processing begins.
+if (args.mailboxDir) {
+	proc.stdin.write(JSON.stringify({ type: "set_steering_mode", mode: "all" }) + "\n");
+	process.stderr.write(`[rpc-wrapper] mailbox enabled: ${args.mailboxDir}\n`);
+}
+
 // ── Stdin Lifecycle ──────────────────────────────────────────────────
 
 /**
@@ -640,11 +811,31 @@ function querySessionStats() {
 
 // ── Route RPC events ─────────────────────────────────────────────────
 
+// Event types worth persisting to the sidecar JSONL.
+// Streaming deltas (content_block_delta, content_block_start/stop, message_start,
+// input_json_delta, etc.) are omitted — they're high-volume, large, and not used
+// by the dashboard or telemetry consumers. A single merge agent can produce 42MB+
+// of sidecar data from streaming deltas alone.
+const SIDECAR_EVENT_TYPES = new Set([
+	"agent_start",
+	"agent_end",
+	"message_end",
+	"tool_execution_start",
+	"tool_execution_end",
+	"tool_execution_update",
+	"auto_retry_start",
+	"auto_retry_end",
+	"auto_compaction_start",
+	"response",
+]);
+
 function handleEvent(event) {
 	if (!event || !event.type) return;
 
-	// Write ALL events to sidecar (redacted)
-	writeSidecarEvent(args.sidecarPath, event);
+	// Write only telemetry-relevant events to sidecar (redacted)
+	if (SIDECAR_EVENT_TYPES.has(event.type)) {
+		writeSidecarEvent(args.sidecarPath, event);
+	}
 
 	// Delegate state mutation to the extracted (testable) accumulator
 	applyEvent(state, event);
@@ -657,6 +848,16 @@ function handleEvent(event) {
 			// Falls back gracefully: older pi versions ignore the command
 			// or return a response without contextUsage — state.contextUsage stays null.
 			querySessionStats();
+			// Check mailbox for pending steering messages (TP-089).
+			// Only active when --mailbox-dir is provided (backward compatible).
+			if (args.mailboxDir) {
+				try {
+					checkMailboxAndSteer(args.mailboxDir, proc);
+				} catch (err) {
+					// Never crash on mailbox I/O errors
+					process.stderr.write(`\n[STEERING] ERROR: ${err.message}\n`);
+				}
+			}
 			break;
 
 		case "tool_execution_start":

package/extensions/task-runner.ts

@@ -1121,7 +1121,7 @@ function extractVerdict(reviewContent: string): string {
 	// TP-068: Tolerate non-standard verdict formats from models that don't
 	// follow the exact template (e.g., "Changes requested", "Needs revision").
 	const lower = reviewContent.toLowerCase();
-	if (/\b(changes?\s+requested|needs?\s+revision|please\s+revise|must\s+revise)\b/.test(lower)) {
+	if (/\b(request\s+changes?|changes?\s+requested|needs?\s+revision|please\s+revise|must\s+revise)\b/.test(lower)) {
 		return "REVISE";
 	}
 	if (/\b(looks?\s+good|no\s+issues?\s+found|approved?)\b/.test(lower)) {
@@ -1835,6 +1835,15 @@ function spawnAgentTmux(opts: {
 	if (opts.extensions && opts.extensions.length > 0) {
 		wrapperArgs.push("--extensions", quoteArg(opts.extensions.join(",")));
 	}
+	// TP-089: Agent mailbox steering — construct mailbox dir when in orchestrator mode.
+	// ORCH_BATCH_ID is set by execution.ts for all lane spawns (including retries).
+	// getSidecarDir() returns the .pi/ directory path (already includes .pi/).
+	const orchBatchId = process.env.ORCH_BATCH_ID;
+	if (orchBatchId) {
+		const mailboxDir = join(getSidecarDir(), "mailbox", orchBatchId, opts.sessionName);
+		mkdirSync(join(mailboxDir, "inbox"), { recursive: true });
+		wrapperArgs.push("--mailbox-dir", quoteArg(mailboxDir));
+	}
 	// Passthrough pi args: flags forwarded to the underlying pi --mode rpc process.
 	// Note: --no-session is NOT passed here — rpc-wrapper.mjs already injects it.
 	wrapperArgs.push("--");

package/extensions/taskplane/cleanup.ts

@@ -19,8 +19,9 @@
  * @module orch/cleanup
  * @since TP-065
  */
-import { existsSync, readdirSync, statSync, unlinkSync, renameSync, mkdirSync } from "fs";
+import { existsSync, readdirSync, statSync, unlinkSync, renameSync, mkdirSync, rmSync } from "fs";
 import { join } from "path";
+import { MAILBOX_DIR_NAME } from "./types.ts";
 
 // ── Layer 1: Post-Integrate Cleanup ─────────────────────────────────
 
@@ -34,6 +35,8 @@ export interface PostIntegrateCleanupResult {
 	mergeFilesDeleted: number;
 	/** Number of lane prompt files deleted */
 	promptFilesDeleted: number;
+	/** Number of mailbox batch directories deleted (0 or 1) */
+	mailboxDirsDeleted: number;
 	/** Warnings from non-fatal cleanup failures */
 	warnings: string[];
 }
@@ -57,6 +60,7 @@ export function cleanupPostIntegrate(stateRoot: string, batchId: string): PostIn
 		telemetryFilesDeleted: 0,
 		mergeFilesDeleted: 0,
 		promptFilesDeleted: 0,
+		mailboxDirsDeleted: 0,
 		warnings: [],
 	};
 
@@ -119,6 +123,17 @@ export function cleanupPostIntegrate(stateRoot: string, batchId: string): PostIn
 		}
 	}
 
+	// ── Mailbox directory (.pi/mailbox/{batchId}/) ───────────
+	const mailboxBatchDir = join(stateRoot, ".pi", MAILBOX_DIR_NAME, batchId);
+	if (existsSync(mailboxBatchDir)) {
+		try {
+			rmSync(mailboxBatchDir, { recursive: true, force: true });
+			result.mailboxDirsDeleted = 1;
+		} catch (err: unknown) {
+			result.warnings.push(`Failed to delete mailbox directory ${mailboxBatchDir}: ${(err as Error).message}`);
+		}
+	}
+
 	return result;
 }
 
@@ -127,13 +142,14 @@ export function cleanupPostIntegrate(stateRoot: string, batchId: string): PostIn
  */
 export function formatPostIntegrateCleanup(result: PostIntegrateCleanupResult): string {
 	const parts: string[] = [];
-	const totalDeleted = result.telemetryFilesDeleted + result.mergeFilesDeleted + result.promptFilesDeleted;
+	const totalDeleted = result.telemetryFilesDeleted + result.mergeFilesDeleted + result.promptFilesDeleted + result.mailboxDirsDeleted;
 
 	if (totalDeleted > 0) {
 		const segments: string[] = [];
 		if (result.telemetryFilesDeleted > 0) segments.push(`${result.telemetryFilesDeleted} telemetry`);
 		if (result.mergeFilesDeleted > 0) segments.push(`${result.mergeFilesDeleted} merge`);
 		if (result.promptFilesDeleted > 0) segments.push(`${result.promptFilesDeleted} prompt`);
+		if (result.mailboxDirsDeleted > 0) segments.push(`${result.mailboxDirsDeleted} mailbox`);
 		parts.push(`🧹 Cleaned up ${totalDeleted} artifact file(s): ${segments.join(", ")}`);
 	}
 
@@ -155,6 +171,8 @@ export const STALE_ARTIFACT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 export interface PreflightSweepResult {
 	/** Number of stale files deleted */
 	staleFilesDeleted: number;
+	/** Number of stale mailbox batch directories deleted */
+	staleDirsDeleted: number;
 	/** Whether the sweep was skipped (e.g., active batch) */
 	skipped: boolean;
 	/** Reason for skipping (if skipped) */
@@ -198,6 +216,7 @@ export function sweepStaleArtifacts(
 ): PreflightSweepResult {
 	const result: PreflightSweepResult = {
 		staleFilesDeleted: 0,
+		staleDirsDeleted: 0,
 		skipped: false,
 		warnings: [],
 	};
@@ -255,6 +274,29 @@ export function sweepStaleArtifacts(
 		(name.startsWith("merge-request-") && name.endsWith(".txt")),
 	);
 
+	// Sweep stale mailbox batch directories (.pi/mailbox/{batchId}/)
+	const mailboxBase = join(stateRoot, ".pi", MAILBOX_DIR_NAME);
+	if (existsSync(mailboxBase)) {
+		try {
+			const entries = readdirSync(mailboxBase);
+			for (const entry of entries) {
+				const entryPath = join(mailboxBase, entry);
+				try {
+					const stat = statSync(entryPath);
+					if (!stat.isDirectory()) continue;
+					if (stat.mtimeMs < cutoff) {
+						rmSync(entryPath, { recursive: true, force: true });
+						result.staleDirsDeleted++;
+					}
+				} catch (err: unknown) {
+					result.warnings.push(`Failed to process mailbox dir ${entry}: ${(err as Error).message}`);
+				}
+			}
+		} catch (err: unknown) {
+			result.warnings.push(`Failed to read mailbox directory ${mailboxBase}: ${(err as Error).message}`);
+		}
+	}
+
 	return result;
 }
 
@@ -265,12 +307,15 @@ export function formatPreflightSweep(result: PreflightSweepResult): string {
 	if (result.skipped) {
 		return `ℹ️ Preflight sweep skipped: ${result.skipReason}`;
 	}
-	if (result.staleFilesDeleted === 0 && result.warnings.length === 0) {
+	if (result.staleFilesDeleted === 0 && result.staleDirsDeleted === 0 && result.warnings.length === 0) {
 		return ""; // Nothing to report
 	}
 	const parts: string[] = [];
-	if (result.staleFilesDeleted > 0) {
-		parts.push(`🧹 Preflight cleanup: removed ${result.staleFilesDeleted} stale artifact(s) (>7 days old)`);
+	if (result.staleFilesDeleted > 0 || result.staleDirsDeleted > 0) {
+		const segments: string[] = [];
+		if (result.staleFilesDeleted > 0) segments.push(`${result.staleFilesDeleted} stale artifact(s)`);
+		if (result.staleDirsDeleted > 0) segments.push(`${result.staleDirsDeleted} stale mailbox dir(s)`);
+		parts.push(`🧹 Preflight cleanup: removed ${segments.join(" and ")} (>7 days old)`);
 	}
 	for (const warning of result.warnings) {
 		parts.push(`  ⚠️ ${warning}`);
@@ -396,8 +441,11 @@ export function formatPreflightCleanup(result: PreflightCleanupResult): string {
 	const parts: string[] = [];
 
 	// Layer 2: age-based sweep
-	if (!result.sweep.skipped && result.sweep.staleFilesDeleted > 0) {
-		parts.push(`removed ${result.sweep.staleFilesDeleted} stale artifact(s) (>7 days old)`);
+	if (!result.sweep.skipped && (result.sweep.staleFilesDeleted > 0 || result.sweep.staleDirsDeleted > 0)) {
+		const segments: string[] = [];
+		if (result.sweep.staleFilesDeleted > 0) segments.push(`${result.sweep.staleFilesDeleted} stale artifact(s)`);
+		if (result.sweep.staleDirsDeleted > 0) segments.push(`${result.sweep.staleDirsDeleted} stale mailbox dir(s)`);
+		parts.push(`removed ${segments.join(" and ")} (>7 days old)`);
 	}
 
 	// Layer 3: log rotation

package/extensions/taskplane/diagnostics.ts

@@ -139,7 +139,7 @@ export interface ExitSummary {
 	compactions: number;
 	/** Wall-clock duration of the session in seconds (always written, even on crash) */
 	durationSec: number;
-	/** Last tool call description (e.g., "bash: npx vitest run"), null if no tools were called */
+	/** Last tool call description (e.g., "bash: node --test tests/*.test.ts"), null if no tools were called */
 	lastToolCall: string | null;
 	/** Error message if the session ended with an error, null on clean exit */
 	error: string | null;

package/extensions/taskplane/engine-worker.ts

@@ -85,7 +85,7 @@ export interface SerializedWorkspaceConfig {
  * workerData shape passed from the main thread.
  */
 export interface EngineWorkerData {
-	/** Sentinel flag — distinguishes engine worker from vitest threads */
+	/** Sentinel flag — distinguishes engine worker from test-runner worker threads */
 	engineWorker: true;
 	/** "execute" for new batch, "resume" for resume */
 	mode: "execute" | "resume";

package/extensions/taskplane/engine.ts

@@ -228,6 +228,7 @@ async function attemptWorkerCrashRetry(
 				retryPauseSignal,
 				wsRoot,
 				isWsMode,
+				{ ORCH_BATCH_ID: batchState.batchId }, // TP-089: ensure mailbox works for retries
 			);
 
 			const retryOutcome = retryResult.tasks[0];
@@ -484,7 +485,8 @@ async function attemptModelFallbackRetry(
 			const retryPauseSignal = { paused: false };
 			// Pass TASKPLANE_MODEL_FALLBACK=1 as extra env var to signal
 			// the task-runner to use the session model instead of configured model.
-			const modelFallbackEnv = { TASKPLANE_MODEL_FALLBACK: "1" };
+			// TP-089: Also include ORCH_BATCH_ID so mailbox steering works for retries.
+			const modelFallbackEnv = { TASKPLANE_MODEL_FALLBACK: "1", ORCH_BATCH_ID: batchState.batchId };
 			const retryResult = await executeLane(
 				retryLane,
 				orchConfig,

package/extensions/taskplane/execution.ts

@@ -915,10 +915,8 @@ export function spawnLaneSession(
 
 	// Build env vars
 	const envVars = buildLaneEnvVars(lane, task.task.promptPath, repoRoot, workspaceRoot);
-	// Pass batch ID so task-runner can include it in lane state for dashboard filtering
-	if (config.orchestrator?.batchId) {
-		envVars.ORCH_BATCH_ID = config.orchestrator.batchId;
-	}
+	// ORCH_BATCH_ID is passed via extraEnvVars from executeWave → executeLane → spawnLaneSession.
+	// The task-runner reads it to include batchId in lane-state JSON for dashboard filtering.
 	if (extraEnvVars) {
 		Object.assign(envVars, extraEnvVars);
 	}
@@ -2371,7 +2369,9 @@ export async function executeWave(
 	const wsRoot = workspaceConfig ? dirname(dirname(workspaceConfig.configPath)) : undefined;
 	const isWsMode = !!workspaceConfig;
 	const lanePromises = lanes.map(lane =>
-		executeLane(lane, config, repoRoot, wavePauseSignal, wsRoot, isWsMode),
+		executeLane(lane, config, repoRoot, wavePauseSignal, wsRoot, isWsMode, {
+			ORCH_BATCH_ID: batchId,
+		}),
 	);
 
 	// Start monitoring as a sibling async loop

package/extensions/taskplane/extension.ts

@@ -32,6 +32,8 @@ import { runMigrations } from "./migrations.ts";
 import { serializeWorkspaceConfig, applySerializedState, deserializeWorkspaceConfig } from "./engine-worker.ts";
 import type { EngineWorkerData, WorkerToMainMessage } from "./engine-worker.ts";
 import { cleanupPostIntegrate, formatPostIntegrateCleanup, sweepStaleArtifacts, formatPreflightSweep, rotateSupervisorLogs, formatLogRotation } from "./cleanup.ts";
+import { writeMailboxMessage } from "./mailbox.ts";
+import type { MailboxMessageType } from "./types.ts";
 import {
 	activateSupervisor,
 	deactivateSupervisor,
@@ -2992,12 +2994,18 @@ export default function (pi: ExtensionAPI) {
 		if (batchId) {
 			try {
 				const artifactCleanup = cleanupPostIntegrate(repoRoot, batchId);
-				const totalCleaned = artifactCleanup.telemetryFilesDeleted + artifactCleanup.mergeFilesDeleted + artifactCleanup.promptFilesDeleted;
+				const totalCleaned = artifactCleanup.telemetryFilesDeleted + artifactCleanup.mergeFilesDeleted + artifactCleanup.promptFilesDeleted + artifactCleanup.mailboxDirsDeleted;
 				if (totalCleaned > 0) {
+					const cleanupParts = [
+						`${artifactCleanup.telemetryFilesDeleted} telemetry file(s)`,
+						`${artifactCleanup.mergeFilesDeleted} merge result(s)`,
+						`${artifactCleanup.promptFilesDeleted} prompt file(s)`,
+					];
+					if (artifactCleanup.mailboxDirsDeleted > 0) {
+						cleanupParts.push(`${artifactCleanup.mailboxDirsDeleted} mailbox dir(s)`);
+					}
 					outputLines.push(
-						`🧹 Cleaned up ${artifactCleanup.telemetryFilesDeleted} telemetry file(s), ` +
-						`${artifactCleanup.mergeFilesDeleted} merge result(s), ` +
-						`${artifactCleanup.promptFilesDeleted} prompt file(s) for batch ${batchId}`,
+						`🧹 Cleaned up ${cleanupParts.join(", ")} for batch ${batchId}`,
 					);
 				}
 				if (artifactCleanup.warnings.length > 0) {
@@ -3639,6 +3647,112 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	// ── TP-089: Agent Mailbox Steering Tool ──────────────────────────
+
+	pi.registerTool({
+		name: "send_agent_message",
+		label: "Send Agent Message",
+		description:
+			"Send a steering message to a running agent (worker, reviewer, or merger). " +
+			"The message is delivered into the agent's LLM context at the next turn boundary.",
+		promptSnippet: "send_agent_message(to, content, type?) — send steering message to a running agent",
+		promptGuidelines: [
+			"Call send_agent_message to course-correct a running agent (worker, reviewer, or merger).",
+			"The 'to' parameter must be a valid agent session name from the current batch.",
+			"Use orch_status() to see active session names.",
+			"Default type is 'steer' (course correction). Other types: 'query', 'abort', 'info'.",
+			"Messages are limited to 4KB. For larger context, write to a file and reference by path.",
+		],
+		parameters: Type.Object({
+			to: Type.String({
+				description: "Target agent session name (e.g., 'orch-henrylach-lane-1-worker')",
+			}),
+			content: Type.String({
+				description: "Message content (max 4KB). Concise directive for the agent.",
+			}),
+			type: Type.Optional(Type.Union(
+				[Type.Literal("steer"), Type.Literal("query"), Type.Literal("abort"), Type.Literal("info")],
+				{ description: 'Message type (default: "steer")' },
+			)),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			try {
+				const result = doSendAgentMessage(params.to, params.content, params.type ?? "steer", ctx);
+				return { content: [{ type: "text" as const, text: result }], details: undefined };
+			} catch (err) {
+				return {
+					content: [{ type: "text" as const, text: `Error sending message: ${err instanceof Error ? err.message : String(err)}` }],
+					details: undefined,
+				};
+			}
+		},
+	});
+
+	/**
+	 * Send a steering message to a running agent via the mailbox system.
+	 *
+	 * Resolves the target session from batch state, validates it exists,
+	 * and writes the message to the agent's inbox.
+	 *
+	 * @since TP-089
+	 */
+	function doSendAgentMessage(to: string, content: string, messageType: string, ctx: ExtensionContext): string {
+		const stateRoot = execCtx?.workspaceRoot ?? execCtx?.repoRoot ?? ctx.cwd;
+
+		// Validate message type (outbound allowlist: steer, query, abort, info)
+		const validOutboundTypes = new Set(["steer", "query", "abort", "info"]);
+		if (!validOutboundTypes.has(messageType)) {
+			return `❌ Invalid message type "${messageType}". Valid types: steer, query, abort, info.`;
+		}
+
+		// Load batch state
+		let state: PersistedBatchState | null = null;
+		try {
+			state = loadBatchState(stateRoot);
+		} catch (err) {
+			return `❌ Failed to load batch state: ${err instanceof Error ? err.message : String(err)}`;
+		}
+		if (!state) {
+			return "❌ No batch state found. There is no active or recent batch.";
+		}
+
+		// Build the set of valid agent session names from batch state
+		const validSessions = new Set<string>();
+		const orchConfig = execCtx?.orchestratorConfig;
+		const tmuxPrefix = orchConfig?.orchestrator?.tmux_prefix ?? "orch";
+		const opId = orchConfig ? resolveOperatorId(orchConfig) : "op";
+
+		for (const lane of state.lanes) {
+			// Worker and reviewer are derived from lane session name
+			validSessions.add(`${lane.tmuxSessionName}-worker`);
+			validSessions.add(`${lane.tmuxSessionName}-reviewer`);
+			// Merger: {tmuxPrefix}-{opId}-merge-{laneNumber}
+			validSessions.add(`${tmuxPrefix}-${opId}-merge-${lane.laneNumber}`);
+		}
+
+		// Validate target session
+		if (!validSessions.has(to)) {
+			const examples = [...validSessions].slice(0, 5).join(", ");
+			return `❌ Unknown session "${to}" in batch ${state.batchId}.\nValid targets: ${examples}${validSessions.size > 5 ? ` (${validSessions.size} total)` : ""}`;
+		}
+
+		// Write message to inbox
+		try {
+			const msg = writeMailboxMessage(stateRoot, state.batchId, to, {
+				from: "supervisor",
+				type: messageType as MailboxMessageType,
+				content,
+			});
+			return `✅ Message sent to \`${to}\` (batch ${state.batchId})\n` +
+				`- **ID:** ${msg.id}\n` +
+				`- **Type:** ${messageType}\n` +
+				`- **Size:** ${Buffer.byteLength(content, "utf8")} bytes\n` +
+				`Message will be delivered at the agent's next turn boundary.`;
+		} catch (err) {
+			return `❌ Failed to write message: ${err instanceof Error ? err.message : String(err)}`;
+		}
+	}
+
 	// ── Settings TUI ─────────────────────────────────────────────────
 
 	pi.registerCommand("taskplane-settings", {