taskplane 0.22.10 → 0.22.12

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/persistence.ts

@@ -9,7 +9,7 @@ import { join, dirname, basename } from "path";
 import { execLog } from "./execution.ts";
 import { BATCH_STATE_SCHEMA_VERSION, StateFileError, batchStatePath, BATCH_HISTORY_MAX_ENTRIES, defaultResilienceState, defaultBatchDiagnostics } from "./types.ts";
 import type { BatchHistorySummary } from "./types.ts";
-import type { AllocatedLane, DiscoveryResult, EngineEvent, EscalationContext, LaneTaskOutcome, LaneTaskStatus, MonitorState, OrchBatchPhase, OrchBatchRuntimeState, PersistedBatchState, PersistedLaneRecord, PersistedMergeResult, PersistedTaskRecord, TaskMonitorSnapshot, Tier0RecoveryPattern, WorkspaceMode } from "./types.ts";
+import type { AllocatedLane, DiscoveryResult, EngineEvent, EscalationContext, LaneTaskOutcome, LaneTaskStatus, MonitorState, OrchBatchPhase, OrchBatchRuntimeState, PersistedBatchState, PersistedLaneRecord, PersistedMergeResult, PersistedSegmentRecord, PersistedTaskRecord, TaskMonitorSnapshot, Tier0RecoveryPattern, WorkspaceMode } from "./types.ts";
 import { sleepSync } from "./worktree.ts";
 import type { PreserveFailedLaneProgressResult } from "./worktree.ts";
 
@@ -379,6 +379,29 @@ export function upconvertV2toV3(obj: Record<string, unknown>): void {
 	if (!obj.diagnostics) obj.diagnostics = defaultBatchDiagnostics();
 }
 
+/**
+ * Upconvert a v3 state object to v4 by adding the `segments` array.
+ *
+ * Added fields:
+ * - `segments`: empty array (no segment records exist in pre-v4 state)
+ *
+ * Task-level segment fields (`packetRepoId`, `packetTaskPath`,
+ * `segmentIds`, `activeSegmentId`) are optional and default to
+ * `undefined` (omitted from JSON). They are NOT backfilled here
+ * because their values depend on runtime discovery, not on
+ * migration defaults.
+ *
+ * This function is idempotent: calling it on an already-v4 object is a no-op.
+ *
+ * @param obj - Parsed state object (mutated in-place)
+ */
+export function upconvertV3toV4(obj: Record<string, unknown>): void {
+	if ((obj.schemaVersion as number) >= 4) return;
+	obj.schemaVersion = 4;
+	// Backfill v4 segments with empty array only during genuine v3→v4 migration.
+	if (!obj.segments) obj.segments = [];
+}
+
 /**
  * Validate a parsed JSON object as a PersistedBatchState.
  *
@@ -410,9 +433,9 @@ export function validatePersistedState(data: unknown): PersistedBatchState {
 			`Missing or invalid "schemaVersion" field (expected number, got ${typeof obj.schemaVersion})`,
 		);
 	}
-	// Accept v1 (auto-upconvert to v2→v3), v2 (upconvert to v3), and v3 (current).
+	// Accept v1 (auto-upconvert to v2→v3→v4), v2 (upconvert to v3→v4), v3 (upconvert to v4), and v4 (current).
 	// Reject anything else — including future versions from newer runtimes.
-	const ACCEPTED_VERSIONS = [1, 2, BATCH_STATE_SCHEMA_VERSION];
+	const ACCEPTED_VERSIONS = [1, 2, 3, BATCH_STATE_SCHEMA_VERSION];
 	if (!ACCEPTED_VERSIONS.includes(obj.schemaVersion as number)) {
 		throw new StateFileError(
 			"STATE_SCHEMA_INVALID",
@@ -754,12 +777,13 @@ export function validatePersistedState(data: unknown): PersistedBatchState {
 		}
 	}
 
-	// ── v1→v2→v3 upconversion ────────────────────────────────────
+	// ── v1→v2→v3→v4 upconversion ─────────────────────────────────
 	// Apply defaults for fields that may be absent in older state files.
 	// The on-disk file is NOT rewritten; upconversion is in-memory only.
-	// Chain: v1→v2 then v2→v3 (each is idempotent / no-op if already at target).
+	// Chain: v1→v2 then v2→v3 then v3→v4 (each is idempotent / no-op if already at target).
 	upconvertV1toV2(obj);
 	upconvertV2toV3(obj);
+	upconvertV3toV4(obj);
 
 	// ── Validate v3 resilience section ───────────────────────────
 	// After upconversion, resilience must be a valid object with correct types.
@@ -928,6 +952,127 @@ export function validatePersistedState(data: unknown): PersistedBatchState {
 				);
 			}
 		}
+		// v4 optional fields: packetRepoId, packetTaskPath (string | undefined)
+		if (t.packetRepoId !== undefined && typeof t.packetRepoId !== "string") {
+			throw new StateFileError(
+				"STATE_SCHEMA_INVALID",
+				`tasks[${i}].packetRepoId is not a string (got ${typeof t.packetRepoId})`,
+			);
+		}
+		if (t.packetTaskPath !== undefined && typeof t.packetTaskPath !== "string") {
+			throw new StateFileError(
+				"STATE_SCHEMA_INVALID",
+				`tasks[${i}].packetTaskPath is not a string (got ${typeof t.packetTaskPath})`,
+			);
+		}
+		// v4 optional field: segmentIds (string[] | undefined)
+		if (t.segmentIds !== undefined) {
+			if (!Array.isArray(t.segmentIds)) {
+				throw new StateFileError(
+					"STATE_SCHEMA_INVALID",
+					`tasks[${i}].segmentIds is not an array (got ${typeof t.segmentIds})`,
+				);
+			}
+			for (let j = 0; j < (t.segmentIds as unknown[]).length; j++) {
+				if (typeof (t.segmentIds as unknown[])[j] !== "string") {
+					throw new StateFileError(
+						"STATE_SCHEMA_INVALID",
+						`tasks[${i}].segmentIds[${j}] is not a string`,
+					);
+				}
+			}
+		}
+		// v4 optional field: activeSegmentId (string | null | undefined)
+		if (t.activeSegmentId !== undefined && t.activeSegmentId !== null && typeof t.activeSegmentId !== "string") {
+			throw new StateFileError(
+				"STATE_SCHEMA_INVALID",
+				`tasks[${i}].activeSegmentId is not a string or null (got ${typeof t.activeSegmentId})`,
+			);
+		}
+	}
+
+	// ── Validate v4 segments array ───────────────────────────────
+	if (!Array.isArray(obj.segments)) {
+		throw new StateFileError(
+			"STATE_SCHEMA_INVALID",
+			`Missing or invalid "segments" field (expected array, got ${typeof obj.segments})`,
+		);
+	}
+	const segments = obj.segments as unknown[];
+	for (let i = 0; i < segments.length; i++) {
+		const s = segments[i] as Record<string, unknown>;
+		if (!s || typeof s !== "object") {
+			throw new StateFileError(
+				"STATE_SCHEMA_INVALID",
+				`segments[${i}] is not an object`,
+			);
+		}
+		// Required string fields
+		for (const field of ["segmentId", "taskId", "repoId", "laneId", "sessionName", "worktreePath", "branch", "exitReason"] as const) {
+			if (typeof s[field] !== "string") {
+				throw new StateFileError(
+					"STATE_SCHEMA_INVALID",
+					`segments[${i}].${field} is missing or not a string (got ${typeof s[field]})`,
+				);
+			}
+		}
+		// Required status field (same valid values as task status)
+		if (typeof s.status !== "string" || !VALID_TASK_STATUSES.has(s.status)) {
+			throw new StateFileError(
+				"STATE_SCHEMA_INVALID",
+				`segments[${i}].status is invalid: "${s.status}" (expected one of: ${[...VALID_TASK_STATUSES].join(", ")})`,
+			);
+		}
+		// Nullable number fields: startedAt, endedAt
+		if (s.startedAt !== null && typeof s.startedAt !== "number") {
+			throw new StateFileError(
+				"STATE_SCHEMA_INVALID",
+				`segments[${i}].startedAt is not a number or null (got ${typeof s.startedAt})`,
+			);
+		}
+		if (s.endedAt !== null && typeof s.endedAt !== "number") {
+			throw new StateFileError(
+				"STATE_SCHEMA_INVALID",
+				`segments[${i}].endedAt is not a number or null (got ${typeof s.endedAt})`,
+			);
+		}
+		// Required number: retries
+		if (typeof s.retries !== "number") {
+			throw new StateFileError(
+				"STATE_SCHEMA_INVALID",
+				`segments[${i}].retries is not a number (got ${typeof s.retries})`,
+			);
+		}
+		// Required array: dependsOnSegmentIds
+		if (!Array.isArray(s.dependsOnSegmentIds)) {
+			throw new StateFileError(
+				"STATE_SCHEMA_INVALID",
+				`segments[${i}].dependsOnSegmentIds is not an array (got ${typeof s.dependsOnSegmentIds})`,
+			);
+		}
+		for (let j = 0; j < (s.dependsOnSegmentIds as unknown[]).length; j++) {
+			if (typeof (s.dependsOnSegmentIds as unknown[])[j] !== "string") {
+				throw new StateFileError(
+					"STATE_SCHEMA_INVALID",
+					`segments[${i}].dependsOnSegmentIds[${j}] is not a string`,
+				);
+			}
+		}
+		// Optional exitDiagnostic
+		if (s.exitDiagnostic !== undefined) {
+			if (!s.exitDiagnostic || typeof s.exitDiagnostic !== "object" || Array.isArray(s.exitDiagnostic)) {
+				throw new StateFileError(
+					"STATE_SCHEMA_INVALID",
+					`segments[${i}].exitDiagnostic is not a plain object (got ${Array.isArray(s.exitDiagnostic) ? "array" : typeof s.exitDiagnostic})`,
+				);
+			}
+			if (typeof (s.exitDiagnostic as Record<string, unknown>).classification !== "string") {
+				throw new StateFileError(
+					"STATE_SCHEMA_INVALID",
+					`segments[${i}].exitDiagnostic.classification is not a string`,
+				);
+			}
+		}
 	}
 
 	// ── Capture unknown top-level fields for roundtrip preservation ──
@@ -941,6 +1086,7 @@ export function validatePersistedState(data: unknown): PersistedBatchState {
 		"totalTasks", "succeededTasks", "failedTasks", "skippedTasks", "blockedTasks",
 		"blockedTaskIds", "lastError", "errors",
 		"resilience", "diagnostics",
+		"segments",
 		"_extraFields",
 	]);
 	const extraFields: Record<string, unknown> = {};
@@ -1049,6 +1195,20 @@ export function serializeBatchState(
 				record.exitDiagnostic = outcome.exitDiagnostic;
 			}
 
+			// TP-081 v4: Serialize segment-level fields from ParsedTask or existing state
+			if (allocated?.allocatedTask.task?.packetRepoId !== undefined) {
+				(record as any).packetRepoId = allocated.allocatedTask.task.packetRepoId;
+			}
+			if (allocated?.allocatedTask.task?.packetTaskPath !== undefined) {
+				(record as any).packetTaskPath = allocated.allocatedTask.task.packetTaskPath;
+			}
+			if (allocated?.allocatedTask.task?.segmentIds !== undefined) {
+				(record as any).segmentIds = allocated.allocatedTask.task.segmentIds;
+			}
+			if (allocated?.allocatedTask.task?.activeSegmentId !== undefined) {
+				(record as any).activeSegmentId = allocated.allocatedTask.task.activeSegmentId;
+			}
+
 			return record;
 		});
 
@@ -1122,6 +1282,7 @@ export function serializeBatchState(
 		errors: [...state.errors],
 		resilience: state.resilience ?? defaultResilienceState(),
 		diagnostics: state.diagnostics ?? defaultBatchDiagnostics(),
+		segments: state.segments ?? [],
 	};
 
 	// Merge unknown fields from loaded state to preserve roundtrip fidelity.

package/extensions/taskplane/resume.ts

@@ -1167,7 +1167,9 @@ export async function resumeOrchBatch(
 			});
 
 			try {
-				spawnLaneSession(lane, allocatedTask, orchConfig, reExecRepoRoot);
+				spawnLaneSession(lane, allocatedTask, orchConfig, reExecRepoRoot, undefined, {
+					ORCH_BATCH_ID: batchState.batchId,
+				});
 				const pollResult = await pollUntilTaskComplete(
 					lane,
 					allocatedTask,

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