taskplane 0.22.11 → 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 ──────────────────────────────────────────────────
 
 /**
@@ -677,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

@@ -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/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", {

package/extensions/taskplane/mailbox.ts

@@ -0,0 +1,341 @@
+/**
+ * Agent Mailbox — file-based cross-agent messaging utilities.
+ *
+ * Provides the core mailbox operations for the agent-mailbox-steering
+ * protocol: write, read, and acknowledge messages in batch-scoped,
+ * session-scoped inbox directories.
+ *
+ * Directory structure:
+ * ```
+ * .pi/mailbox/{batchId}/
+ * ├── {sessionName}/
+ * │   ├── inbox/          ← pending messages
+ * │   └── ack/            ← processed messages (moved from inbox)
+ * └── _broadcast/
+ *     └── inbox/          ← messages to all agents
+ * ```
+ *
+ * All file operations are synchronous (matching rpc-wrapper pattern).
+ * Write operations are atomic (temp file + rename in same directory).
+ * Read/ack operations are best-effort (log warnings, don't crash).
+ *
+ * @module orch/mailbox
+ * @since TP-089
+ */
+
+import { join, dirname } from "path";
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, renameSync, unlinkSync } from "fs";
+import { randomBytes } from "crypto";
+import type { MailboxMessage, MailboxMessageType, WriteMailboxMessageOpts } from "./types.ts";
+import { MAILBOX_DIR_NAME, MAILBOX_MAX_CONTENT_BYTES, MAILBOX_MESSAGE_TYPES } from "./types.ts";
+
+// ── Path Helpers ─────────────────────────────────────────────────────
+
+/**
+ * Root directory for all mailboxes in a batch.
+ *
+ * @param stateRoot - Root directory containing .pi/ (workspace root or repo root)
+ * @param batchId - Batch ID for scoping
+ * @returns Absolute path: `{stateRoot}/.pi/mailbox/{batchId}/`
+ *
+ * @since TP-089
+ */
+export function mailboxRoot(stateRoot: string, batchId: string): string {
+	return join(stateRoot, ".pi", MAILBOX_DIR_NAME, batchId);
+}
+
+/**
+ * Inbox directory for a specific agent session.
+ *
+ * @param stateRoot - Root directory containing .pi/
+ * @param batchId - Batch ID
+ * @param sessionName - tmux session name (unique per batch)
+ * @returns Absolute path: `{stateRoot}/.pi/mailbox/{batchId}/{sessionName}/inbox/`
+ *
+ * @since TP-089
+ */
+export function sessionInboxDir(stateRoot: string, batchId: string, sessionName: string): string {
+	return join(stateRoot, ".pi", MAILBOX_DIR_NAME, batchId, sessionName, "inbox");
+}
+
+/**
+ * Ack directory for a specific agent session.
+ *
+ * @param stateRoot - Root directory containing .pi/
+ * @param batchId - Batch ID
+ * @param sessionName - tmux session name
+ * @returns Absolute path: `{stateRoot}/.pi/mailbox/{batchId}/{sessionName}/ack/`
+ *
+ * @since TP-089
+ */
+export function sessionAckDir(stateRoot: string, batchId: string, sessionName: string): string {
+	return join(stateRoot, ".pi", MAILBOX_DIR_NAME, batchId, sessionName, "ack");
+}
+
+/**
+ * Broadcast inbox directory (messages to all agents).
+ *
+ * @param stateRoot - Root directory containing .pi/
+ * @param batchId - Batch ID
+ * @returns Absolute path: `{stateRoot}/.pi/mailbox/{batchId}/_broadcast/inbox/`
+ *
+ * @since TP-089
+ */
+export function broadcastInboxDir(stateRoot: string, batchId: string): string {
+	return join(stateRoot, ".pi", MAILBOX_DIR_NAME, batchId, "_broadcast", "inbox");
+}
+
+
+// ── Write ────────────────────────────────────────────────────────────
+
+/**
+ * Write a message to a target agent's inbox.
+ *
+ * Generates a unique message ID and writes the message atomically
+ * (temp file + rename in the same directory). The temp file uses a
+ * `.msg.json.tmp` extension that is excluded by the inbox reader's
+ * `*.msg.json` filter.
+ *
+ * @param stateRoot - Root directory containing .pi/
+ * @param batchId - Current batch ID
+ * @param to - Target session name or `"_broadcast"`
+ * @param opts - Message content and metadata from the caller
+ * @returns The written MailboxMessage (including generated fields)
+ * @throws If content exceeds 4KB UTF-8 bytes or file I/O fails
+ *
+ * @since TP-089
+ */
+export function writeMailboxMessage(
+	stateRoot: string,
+	batchId: string,
+	to: string,
+	opts: WriteMailboxMessageOpts,
+): MailboxMessage {
+	// Validate content size (UTF-8 bytes, not string length)
+	const contentBytes = Buffer.byteLength(opts.content, "utf8");
+	if (contentBytes > MAILBOX_MAX_CONTENT_BYTES) {
+		throw new Error(
+			`Mailbox message content exceeds ${MAILBOX_MAX_CONTENT_BYTES} byte limit ` +
+			`(${contentBytes} bytes). Steering messages should be concise directives. ` +
+			`Write larger context to a file and reference it by path.`,
+		);
+	}
+
+	// Generate unique message ID
+	const timestamp = Date.now();
+	const nonce = randomBytes(3).toString("hex").slice(0, 5);
+	const id = `${timestamp}-${nonce}`;
+
+	// Build the full message
+	const message: MailboxMessage = {
+		id,
+		batchId,
+		from: opts.from,
+		to,
+		timestamp,
+		type: opts.type,
+		content: opts.content,
+		expectsReply: opts.expectsReply ?? false,
+		replyTo: opts.replyTo ?? null,
+	};
+
+	// Determine inbox directory
+	const inboxDir = to === "_broadcast"
+		? broadcastInboxDir(stateRoot, batchId)
+		: sessionInboxDir(stateRoot, batchId, to);
+
+	// Ensure inbox directory exists
+	mkdirSync(inboxDir, { recursive: true });
+
+	// Atomic write: temp file (.msg.json.tmp) then rename to final (.msg.json)
+	const finalFilename = `${id}.msg.json`;
+	const tempFilename = `${id}.msg.json.tmp`;
+	const tempPath = join(inboxDir, tempFilename);
+	const finalPath = join(inboxDir, finalFilename);
+
+	try {
+		writeFileSync(tempPath, JSON.stringify(message, null, 2) + "\n", "utf-8");
+		renameSync(tempPath, finalPath);
+	} catch (err) {
+		// Attempt cleanup of temp file on failure
+		try {
+			if (existsSync(tempPath)) unlinkSync(tempPath);
+		} catch {
+			// Best effort cleanup
+		}
+		throw new Error(
+			`Failed to write mailbox message to ${finalPath}: ${err instanceof Error ? err.message : String(err)}`,
+		);
+	}
+
+	return message;
+}
+
+
+// ── Read ─────────────────────────────────────────────────────────────
+
+/**
+ * Read pending messages from an inbox directory.
+ *
+ * Returns messages sorted by timestamp (ascending), with filename
+ * lexical order as tie-breaker. Only reads files matching the
+ * `*.msg.json` pattern (excludes `.msg.json.tmp` temp files).
+ *
+ * Messages with invalid shape or mismatched batchId are logged as
+ * warnings and left in the inbox (no throw/crash).
+ *
+ * @param inboxDir - Absolute path to the inbox directory
+ * @param expectedBatchId - Expected batch ID for validation
+ * @returns Sorted array of `{ filename, message }` entries
+ *
+ * @since TP-089
+ */
+export function readInbox(
+	inboxDir: string,
+	expectedBatchId: string,
+): Array<{ filename: string; message: MailboxMessage }> {
+	// Return empty if directory doesn't exist
+	if (!existsSync(inboxDir)) return [];
+
+	let entries: string[];
+	try {
+		entries = readdirSync(inboxDir);
+	} catch (err) {
+		process.stderr.write(
+			`[mailbox] WARNING: failed to read inbox ${inboxDir}: ${err instanceof Error ? err.message : String(err)}\n`,
+		);
+		return [];
+	}
+
+	// Filter: only *.msg.json files (excludes .msg.json.tmp, .tmp, etc.)
+	const msgFiles = entries.filter(f => f.endsWith(".msg.json") && !f.endsWith(".msg.json.tmp"));
+
+	const results: Array<{ filename: string; message: MailboxMessage }> = [];
+
+	for (const filename of msgFiles) {
+		const filePath = join(inboxDir, filename);
+		let raw: string;
+		try {
+			raw = readFileSync(filePath, "utf-8");
+		} catch (err) {
+			process.stderr.write(
+				`[mailbox] WARNING: failed to read ${filePath}: ${err instanceof Error ? err.message : String(err)}\n`,
+			);
+			continue;
+		}
+
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			process.stderr.write(
+				`[mailbox] WARNING: malformed JSON in ${filename}, skipping\n`,
+			);
+			continue;
+		}
+
+		// Validate shape
+		if (!isValidMailboxMessage(parsed)) {
+			process.stderr.write(
+				`[mailbox] WARNING: invalid message shape in ${filename}, skipping\n`,
+			);
+			continue;
+		}
+
+		const msg = parsed as MailboxMessage;
+
+		// Validate batchId
+		if (msg.batchId !== expectedBatchId) {
+			process.stderr.write(
+				`[mailbox] WARNING: batchId mismatch in ${filename} (expected ${expectedBatchId}, got ${msg.batchId}), skipping\n`,
+			);
+			continue;
+		}
+
+		results.push({ filename, message: msg });
+	}
+
+	// Sort: primary by timestamp (ascending), tie-break by filename lexical
+	results.sort((a, b) => {
+		const tsDiff = a.message.timestamp - b.message.timestamp;
+		if (tsDiff !== 0) return tsDiff;
+		return a.filename.localeCompare(b.filename);
+	});
+
+	return results;
+}
+
+
+// ── Acknowledge ──────────────────────────────────────────────────────
+
+/**
+ * Move a message from inbox to ack directory.
+ *
+ * Atomic rename. If the file is already gone (another process acked it),
+ * returns false. The ack directory is derived structurally from the inbox
+ * directory: `dirname(inboxDir)/ack/`.
+ *
+ * @param inboxDir - Absolute path to the inbox directory
+ * @param filename - Message filename (e.g., `1774744971303-a7f2c.msg.json`)
+ * @returns true if acked successfully, false if already acked (ENOENT race)
+ *
+ * @since TP-089
+ */
+export function ackMessage(inboxDir: string, filename: string): boolean {
+	const ackDir = join(dirname(inboxDir), "ack");
+
+	try {
+		mkdirSync(ackDir, { recursive: true });
+	} catch (err) {
+		process.stderr.write(
+			`[mailbox] WARNING: failed to create ack dir ${ackDir}: ${err instanceof Error ? err.message : String(err)}\n`,
+		);
+		return false;
+	}
+
+	const srcPath = join(inboxDir, filename);
+	const dstPath = join(ackDir, filename);
+
+	try {
+		renameSync(srcPath, dstPath);
+		return true;
+	} catch (err: unknown) {
+		const code = (err as NodeJS.ErrnoException).code;
+		if (code === "ENOENT") {
+			// Another process already acked this message — race is harmless
+			return false;
+		}
+		process.stderr.write(
+			`[mailbox] WARNING: failed to ack ${filename}: ${err instanceof Error ? err.message : String(err)}\n`,
+		);
+		return false;
+	}
+}
+
+
+// ── Validation ───────────────────────────────────────────────────────
+
+/**
+ * Runtime validation for mailbox message shape.
+ *
+ * Checks that all required fields are present and correctly typed.
+ * Does not validate batchId match (caller's responsibility).
+ *
+ * @param obj - Parsed JSON value to validate
+ * @returns true if obj is a valid MailboxMessage shape
+ *
+ * @since TP-089
+ */
+export function isValidMailboxMessage(obj: unknown): obj is MailboxMessage {
+	if (!obj || typeof obj !== "object") return false;
+	const m = obj as Record<string, unknown>;
+	return (
+		typeof m.id === "string" &&
+		typeof m.batchId === "string" &&
+		typeof m.from === "string" &&
+		typeof m.to === "string" &&
+		typeof m.timestamp === "number" && Number.isFinite(m.timestamp) &&
+		typeof m.type === "string" && MAILBOX_MESSAGE_TYPES.has(m.type) &&
+		typeof m.content === "string"
+	);
+}

package/extensions/taskplane/merge.ts

@@ -585,6 +585,7 @@ export async function spawnMergeAgent(
 	config: OrchestratorConfig,
 	stateRoot?: string,
 	agentRoot?: string,
+	batchId?: string,
 ): Promise<void> {
 	execLog("merge", sessionName, "preparing to spawn merge agent", {
 		mergeWorkDir,
@@ -658,6 +659,14 @@ export async function spawnMergeAgent(
 		wrapperParts.push("--tools", shellQuote(config.merge.tools));
 	}
 
+	// TP-089: Agent mailbox steering — pass --mailbox-dir when batchId is available.
+	if (batchId) {
+		const mailboxDir = join(sidecarRoot, "mailbox", batchId, sessionName);
+		mkdirSync(join(mailboxDir, "inbox"), { recursive: true });
+		wrapperParts.push("--mailbox-dir", shellQuote(mailboxDir));
+		execLog("merge", sessionName, "mailbox enabled", { mailboxDir });
+	}
+
 	const piCommand = wrapperParts.filter(Boolean).join(" ");
 
 	const tmuxMergeDir = toTmuxPath(mergeWorkDir);
@@ -1511,12 +1520,12 @@ export async function mergeWave(
 						}
 
 						// Re-spawn merge agent for the retry
-						await spawnMergeAgent(sessionName, repoRoot, mergeWorkDir, requestFilePath, config, stateRoot, agentRoot);
+						await spawnMergeAgent(sessionName, repoRoot, mergeWorkDir, requestFilePath, config, stateRoot, agentRoot, batchId);
 						// TP-056: Re-register with health monitor after respawn
 						if (healthMonitor) healthMonitor.addSession(sessionName, lane.laneNumber, resultFilePath);
 					} else {
 						// First attempt: spawn merge agent
-						await spawnMergeAgent(sessionName, repoRoot, mergeWorkDir, requestFilePath, config, stateRoot, agentRoot);
+						await spawnMergeAgent(sessionName, repoRoot, mergeWorkDir, requestFilePath, config, stateRoot, agentRoot, batchId);
 						// TP-056: Register session with health monitor
 						if (healthMonitor) healthMonitor.addSession(sessionName, lane.laneNumber, resultFilePath);
 					}

package/extensions/taskplane/supervisor-primer.md

@@ -332,7 +332,7 @@ git log --oneline orch/{branch}..task/{lane-branch}  # empty = already merged
 4. After merge, run tests to verify:
    ```bash
    git worktree add /tmp/verify orch/{orchBranch} --detach
-   cd /tmp/verify && cd extensions && npx vitest run
+   cd /tmp/verify && cd extensions && node --experimental-strip-types --experimental-test-module-mocks --no-warnings --import ./tests/loader.mjs --test tests/*.test.ts
    ```
 5. Update batch state and advance.
 
@@ -545,7 +545,7 @@ git worktree remove .worktrees/{opId}-{batchId}/merge --force
 ### Verify orch branch integrity
 ```bash
 git worktree add /tmp/tp-verify orch/{orchBranch} --detach
-cd /tmp/tp-verify/extensions && npx vitest run
+cd /tmp/tp-verify/extensions && node --experimental-strip-types --experimental-test-module-mocks --no-warnings --import ./tests/loader.mjs --test tests/*.test.ts
 # Clean up: cd {repoRoot} && git worktree remove /tmp/tp-verify --force
 ```
 
@@ -1333,7 +1333,7 @@ before writing** — if files already exist (partial setup), read and merge.
 **Customization notes:**
 - `project.name`: Use the actual project name (from package.json, README, etc.)
 - `paths.tasks` and `taskAreas`: Match what was agreed in the task area discussion
-- `testing.commands`: Use the detected test command as a named object (e.g., `{"test": "cd extensions && npx vitest run"}`)
+- `testing.commands`: Use the detected test command as a named object (e.g., `{"test": "cd extensions && node --experimental-strip-types --experimental-test-module-mocks --no-warnings --import ./tests/loader.mjs --test tests/*.test.ts"}`)
 - `orchestrator.spawnMode`: Use `"tmux"` if tmux is available, `"subprocess"` otherwise
 - `orchestrator.maxLanes`: Start with 2 for first-time users (safe default)
 - `merge.verify`: Add the project's test command for post-merge verification

package/extensions/taskplane/supervisor.ts

@@ -103,7 +103,7 @@ export const ACTION_CLASSIFICATION_EXAMPLES: Readonly<Record<RecoveryActionClass
 	diagnostic: [
 		"Reading batch-state.json, STATUS.md, events.jsonl, merge results",
 		"Running git status, git log, git diff",
-		"Running test suites (npx vitest run, etc.)",
+		"Running test suites (node --experimental-strip-types --experimental-test-module-mocks --no-warnings --import ./tests/loader.mjs --test ..., etc.)",
 		"Listing tmux sessions (tmux list-sessions)",
 		"Checking worktree health (git worktree list)",
 		"Reading any file for diagnostics",
@@ -2051,7 +2051,7 @@ Every action you take falls into one of three categories:
 ### Diagnostic (always allowed — no confirmation needed)
 - Reading batch-state.json, STATUS.md, events.jsonl, merge results
 - Running \`git status\`, \`git log\`, \`git diff\`
-- Running test suites (\`npx vitest run\`, etc.)
+- Running test suites (\`node --experimental-strip-types --experimental-test-module-mocks --no-warnings --import ./tests/loader.mjs --test ...\`, etc.)
 - Listing tmux sessions (\`tmux list-sessions\`)
 - Checking worktree health (\`git worktree list\`)
 - Reading any file for diagnostics

package/extensions/taskplane/types.ts

@@ -225,7 +225,7 @@ export interface TaskArea {
 export interface TaskRunnerConfig {
 	task_areas: Record<string, TaskArea>;
 	reference_docs: Record<string, string>;
-	/** Named testing/verification commands (e.g., { test: "npx vitest run" }). Used for baseline fingerprinting (TP-032). */
+	/** Named testing/verification commands (e.g., { test: "node --test tests/*.test.ts" }). Used for baseline fingerprinting (TP-032). */
 	testing_commands?: Record<string, string>;
 	/**
 	 * Model fallback behavior when a configured model becomes unavailable mid-batch.
@@ -3357,3 +3357,97 @@ export function createRepoModeContext(
 	};
 }
 
+
+// ── Agent Mailbox Types (TP-089) ─────────────────────────────────────
+
+/**
+ * Mailbox directory name under .pi/.
+ * @since TP-089
+ */
+export const MAILBOX_DIR_NAME = "mailbox";
+
+/**
+ * Maximum content size in UTF-8 bytes.
+ * Steering messages should be concise directives; larger context should be
+ * written to a separate file and referenced by path.
+ * @since TP-089
+ */
+export const MAILBOX_MAX_CONTENT_BYTES = 4096;
+
+/**
+ * Message types for the agent mailbox system.
+ *
+ * | Type       | Direction           | Purpose                                    |
+ * |------------|---------------------|--------------------------------------------|
+ * | `steer`    | supervisor → agent  | Course correction. Agent must follow.       |
+ * | `query`    | supervisor → agent  | Request for status/info. Agent replies.     |
+ * | `abort`    | supervisor → agent  | Graceful stop. Agent wraps up and exits.    |
+ * | `info`     | supervisor → agent  | FYI context. No action required.            |
+ * | `reply`    | agent → supervisor  | Response to query or steer acknowledgment.  |
+ * | `escalate` | agent → supervisor  | Agent-initiated: blocked or needs guidance. |
+ *
+ * @since TP-089
+ */
+export type MailboxMessageType = "steer" | "query" | "abort" | "info" | "reply" | "escalate";
+
+/**
+ * Set of valid mailbox message types for runtime validation.
+ * @since TP-089
+ */
+export const MAILBOX_MESSAGE_TYPES: ReadonlySet<string> = new Set<MailboxMessageType>([
+	"steer", "query", "abort", "info", "reply", "escalate",
+]);
+
+/**
+ * Message format for the file-based agent mailbox.
+ *
+ * Messages are written as JSON files in batch-scoped, session-scoped
+ * directories. The rpc-wrapper checks the inbox on every `message_end`
+ * event and injects pending messages into the agent's LLM context via
+ * pi's `steer` RPC command.
+ *
+ * @see docs/specifications/taskplane/agent-mailbox-steering.md
+ * @since TP-089
+ */
+export interface MailboxMessage {
+	/** Unique message ID: `{timestamp}-{5char-hex-nonce}` */
+	id: string;
+	/** Batch ID — must match current batch for validation */
+	batchId: string;
+	/** Sender identifier: `"supervisor"` or session name */
+	from: string;
+	/** Target session name or `"_broadcast"` */
+	to: string;
+	/** Epoch milliseconds (Date.now()) */
+	timestamp: number;
+	/** Message type */
+	type: MailboxMessageType;
+	/** Message body (max 4KB UTF-8 bytes) */
+	content: string;
+	/** Whether the sender expects a reply (default: false) */
+	expectsReply?: boolean;
+	/** Reference to a previous message ID for threading (default: null) */
+	replyTo?: string | null;
+}
+
+/**
+ * Input options for writeMailboxMessage.
+ *
+ * The caller provides these fields; the utility generates `id`, `batchId`,
+ * `to`, and `timestamp` from its own arguments.
+ *
+ * @since TP-089
+ */
+export interface WriteMailboxMessageOpts {
+	/** Sender identifier: `"supervisor"` or session name */
+	from: string;
+	/** Message type */
+	type: MailboxMessageType;
+	/** Message body (max 4KB UTF-8 bytes) */
+	content: string;
+	/** Whether the sender expects a reply (default: false) */
+	expectsReply?: boolean;
+	/** Reference to a previous message ID for threading (default: null) */
+	replyTo?: string | null;
+}
+

package/extensions/taskplane/verification.ts

@@ -27,10 +27,15 @@
  *   6. Truncate to 512 chars (bound fingerprint size)
  *
  * **Fallback for non-JSON output:**
- *   If vitest JSON parsing fails (truncated, missing, non-JSON), produce a
- *   single fingerprint with kind: "command_error" and the first 512 chars
+ *   If legacy Vitest JSON parsing fails (truncated, missing, non-JSON), produce
+ *   a single fingerprint with kind: "command_error" and the first 512 chars
  *   of stderr (or stdout) as messageNorm.
  *
+ * **Compatibility note:**
+ *   Taskplane's default tests use Node.js native `node:test`. The Vitest parser
+ *   in this module is retained only for backward compatibility when projects
+ *   provide custom `testing.commands` that still emit Vitest JSON.
+ *
  * @module orch/verification
  */
 import { spawnSync } from "child_process";
@@ -300,20 +305,20 @@ function classifyFailureKind(message: string): TestFingerprint["kind"] {
 }
 
 /**
- * Parse vitest JSON reporter output into test fingerprints.
+ * Parse legacy Vitest JSON reporter output into test fingerprints.
  *
- * Expects the stdout to contain a JSON object matching vitest's JSON reporter format.
+ * Expects stdout to contain a JSON object matching Vitest's JSON reporter format.
  * Only failed tests produce fingerprints (passed tests are irrelevant for baseline diffing).
  *
  * If JSON parsing fails or the structure is unexpected, returns null to signal
  * that the caller should use fallback fingerprinting.
  *
  * @param commandId - The command that produced this output
- * @param stdout    - Raw stdout from the vitest command
+ * @param stdout    - Raw stdout from the Vitest command (legacy compatibility path)
  * @returns Array of fingerprints for failed tests, or null if parsing fails
  */
 export function parseVitestOutput(commandId: string, stdout: string): TestFingerprint[] | null {
-	// Try to extract JSON from stdout (vitest may prepend/append non-JSON lines)
+	// Try to extract JSON from stdout (Vitest may prepend/append non-JSON lines)
 	let json: VitestJsonResult;
 	try {
 		// First attempt: parse the whole stdout as JSON
@@ -363,7 +368,7 @@ export function parseVitestOutput(commandId: string, stdout: string): TestFinger
 		}
 
 		// Suite-level failures: testResults[].status === "failed" with no assertion-level details.
-		// This covers setup/import/runtime-at-file-load errors where vitest marks the file as
+		// This covers setup/import/runtime-at-file-load errors where Vitest marks the file as
 		// failed but produces no assertionResults (or only non-failed ones).
 		if (testFile.status === "failed") {
 			const hasFailedAssertions = hasAssertions && assertions!.some(a => a.status === "failed");
@@ -388,7 +393,7 @@ export function parseVitestOutput(commandId: string, stdout: string): TestFinger
  * Parse test output into normalized fingerprints.
  *
  * Strategy:
- * 1. Try vitest JSON adapter
+ * 1. Try legacy Vitest JSON adapter
  * 2. If parsing fails: produce a fallback command_error fingerprint
  *
  * The adapter pattern is extensible — future parsers for jest, pytest, etc.
@@ -416,7 +421,7 @@ export function parseTestOutput(commandResult: CommandResult): TestFingerprint[]
 		return [];
 	}
 
-	// Try vitest JSON adapter
+	// Try legacy Vitest JSON adapter
 	const vitestFingerprints = parseVitestOutput(commandId, stdout);
 	if (vitestFingerprints !== null && vitestFingerprints.length > 0) {
 		return vitestFingerprints;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskplane",
-  "version": "0.22.11",
+  "version": "0.22.12",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",

package/templates/agents/supervisor.md

@@ -68,7 +68,7 @@ Every action you take falls into one of three categories:
 ### Diagnostic (always allowed — no confirmation needed)
 - Reading batch-state.json, STATUS.md, events.jsonl, merge results
 - Running `git status`, `git log`, `git diff`
-- Running test suites (`npx vitest run`, etc.)
+- Running test suites (`node --experimental-strip-types --experimental-test-module-mocks --no-warnings --import ./tests/loader.mjs --test ...`, etc.)
 - Listing tmux sessions (`tmux list-sessions`)
 - Checking worktree health (`git worktree list`)
 - Reading any file for diagnostics

package/templates/agents/task-worker.md

@@ -275,30 +275,24 @@ Run tests at two different scopes depending on where you are in the task:
 
 ### During implementation steps (targeted tests)
 
-After implementing each step, run **targeted tests** for fast feedback:
+After implementing each step, run **targeted tests** for fast feedback.
+Use file-targeted runs for the test files that cover your changes:
 
 ```bash
-cd extensions && npx vitest run --changed
+cd extensions && node --experimental-strip-types --experimental-test-module-mocks --no-warnings --import ./tests/loader.mjs --test tests/some-specific.test.ts
 ```
 
-- Vitest's `--changed` flag uses git to find modified files since the last commit
-  and runs only tests related to those files.
-- Workers commit at step boundaries, so between commits the changed set is
-  exactly "what this step modified" — this naturally targets the right tests.
-- Alternatively, run specific test files that cover the code you modified:
-  `npx vitest run tests/some-specific.test.ts`
-- **If `--changed` returns no tests:** That's fine — it means your changes don't
-  have directly related test files. The full suite in the Testing step will catch
-  any indirect regressions.
-- **If targeted tests fail:** Fix the failure before proceeding. Don't accumulate
-  failures across steps.
+- Node's native runner does not provide a reliable project-level `--changed`
+  equivalent; select targeted files explicitly.
+- If multiple files are relevant, pass multiple `--test` paths.
+- **If targeted tests fail:** fix them before proceeding. Don't accumulate failures.
 
 ### During the Testing & Verification step (full suite)
 
 Run the **full test suite** as a quality gate:
 
 ```bash
-cd extensions && npx vitest run
+cd extensions && node --experimental-strip-types --experimental-test-module-mocks --no-warnings --import ./tests/loader.mjs --test tests/*.test.ts
 ```
 
 - ALL tests must pass — zero failures allowed.