taskplane 0.22.11 → 0.22.13

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
 ```
 
@@ -770,6 +770,12 @@ You have these orchestrator tools available:
 **Note:** `orch_retry_task`, `orch_skip_task`, and `orch_force_merge` require the batch to be paused/stopped first.
 If the batch is actively running, call `orch_pause()` first.
 
+**Diagnostic & Recovery Tools (TP-096):**
+- `read_agent_status(lane?)` — Read STATUS.md + telemetry for a lane (step, progress, context %, cost, elapsed). Omit lane for all lanes.
+- `trigger_wrap_up(lane)` — Write `.task-wrap-up` signal to gracefully stop a worker on a lane.
+- `read_lane_logs(lane)` — Read stderr/crash logs and exit diagnostics for a lane.
+- `list_active_agents()` — List all tmux sessions with role, lane, task, context %, elapsed, cost.
+
 Plus general tools: `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`
 for inspecting files, running git commands, and editing batch state.
 
@@ -1333,7 +1339,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.13",
   "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.