taskplane 0.22.11 → 0.22.13

package/extensions/task-runner.ts

@@ -456,6 +456,34 @@ function writeLaneState(state: TaskState): void {
 	}
 }
 
+/**
+ * Write a context % snapshot at worker iteration boundary (TP-094).
+ * Best-effort JSONL append to `.pi/context-snapshots/{batchId}/{sessionName}.jsonl`.
+ * Non-fatal on any failure — never blocks execution.
+ */
+function writeContextSnapshot(state: TaskState, contextWindow: number): void {
+	const batchId = process.env.ORCH_BATCH_ID || "standalone";
+	const sessionName = isOrchestratedMode() ? `${getTmuxPrefix()}-worker` : "task-worker";
+	try {
+		const dir = join(getSidecarDir(), "context-snapshots", batchId);
+		mkdirSync(dir, { recursive: true });
+		const filePath = join(dir, `${sessionName}.jsonl`);
+		const snapshot = {
+			iteration: state.totalIterations,
+			contextPct: state.workerContextPct,
+			tokens: state.workerInputTokens + state.workerOutputTokens + state.workerCacheReadTokens + state.workerCacheWriteTokens,
+			contextWindow,
+			cost: state.workerCostUsd,
+			toolCalls: state.workerToolCount,
+			exitReason: state.workerExitDiagnostic?.classification || null,
+			timestamp: Date.now(),
+		};
+		appendFileSync(filePath, JSON.stringify(snapshot) + "\n");
+	} catch {
+		// Best effort — don't crash the runner
+	}
+}
+
 /**
  * Append a JSON event to the conversation JSONL log file.
  * Used in orchestrated mode to capture the full worker conversation for the web dashboard.
@@ -1371,7 +1399,9 @@ interface SidecarTelemetryDelta {
 	/** Whether any sidecar events were parsed in this tick (used for callback gating) */
 	hadEvents: boolean;
 	/** Authoritative context usage from pi get_session_stats (pi ≥ 0.63.0, null if unavailable) */
-	contextUsage: { percentUsed: number; totalTokens: number; maxTokens: number } | null;
+	contextUsage: { percent: number; totalTokens: number; maxTokens: number } | null;
+	/** True when a get_session_stats response was seen but lacked contextUsage (older pi) */
+	sawStatsResponseWithoutContextUsage: boolean;
 }
 
 /**
@@ -1390,7 +1420,7 @@ function tailSidecarJsonl(filePath: string, tailState: SidecarTailState): Sideca
 		inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0,
 		cost: 0, latestTotalTokens: 0, toolCalls: 0, lastTool: "",
 		retryActive: tailState.retryActive, retriesStarted: 0, lastRetryError: "",
-		hadEvents: false, contextUsage: null,
+		hadEvents: false, contextUsage: null, sawStatsResponseWithoutContextUsage: false,
 	};
 
 	// Gracefully handle missing file (wrapper hasn't written yet)
@@ -1506,13 +1536,18 @@ function tailSidecarJsonl(filePath: string, tailState: SidecarTailState): Sideca
 				// get_session_stats response from pi ≥ 0.63.0 — authoritative context usage
 				if (event.success === true && event.data?.contextUsage) {
 					const cu = event.data.contextUsage;
-					if (typeof cu.percentUsed === "number") {
+					// pi sends `percent` (pi ≥ 0.63.0); accept `percentUsed` as legacy fallback
+					const pctValue = cu.percent ?? cu.percentUsed;
+					if (typeof pctValue === "number") {
 						delta.contextUsage = {
-							percentUsed: cu.percentUsed,
+							percent: pctValue,
 							totalTokens: cu.totalTokens || 0,
 							maxTokens: cu.maxTokens || 0,
 						};
 					}
+				} else if (event.success === true && event.data && !event.data.contextUsage) {
+					// Successful get_session_stats response but no contextUsage — older pi
+					delta.sawStatsResponseWithoutContextUsage = true;
 				}
 				break;
 			}
@@ -1656,6 +1691,25 @@ export function isLowRiskStep(stepNumber: number, totalSteps: number): boolean {
 
 // ── TMUX Agent Spawner ───────────────────────────────────────────────
 
+/**
+ * Synchronous sleep helper for tmux spawn stabilization checks.
+ *
+ * Uses Atomics.wait for cross-platform blocking delays without relying on
+ * shell `sleep` availability (important on Windows environments).
+ */
+function sleepSyncMs(ms: number): void {
+	if (!Number.isFinite(ms) || ms <= 0) return;
+	try {
+		const arr = new Int32Array(new SharedArrayBuffer(4));
+		Atomics.wait(arr, 0, 0, Math.floor(ms));
+	} catch {
+		const start = Date.now();
+		while (Date.now() - start < ms) {
+			// Busy-wait fallback (rare path)
+		}
+	}
+}
+
 /**
  * Spawns a Pi agent in a named TMUX session instead of a headless subprocess.
  * Returns the same interface shape as `spawnAgent()` for drop-in compatibility.
@@ -1835,6 +1889,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("--");
@@ -1881,6 +1944,73 @@ function spawnAgentTmux(opts: {
 		);
 	}
 
+	// ── TP-095: Post-spawn verification with retry (#335) ──────────
+	// On Windows/MSYS2, rapid sequential tmux session creation is unreliable.
+	// Pi process can exit with code 1 in 0 seconds on the first 3-5 attempts.
+	// Verify the session is alive after a brief delay, and retry if it died.
+	const SPAWN_VERIFY_DELAY_MS = 300;
+	const SPAWN_VERIFY_POLL_ATTEMPTS = 3;
+	const SPAWN_VERIFY_POLL_INTERVAL_MS = 200;
+	const SPAWN_MAX_RETRIES = 2;
+
+	const verifySessionAlive = (): boolean => {
+		for (let poll = 0; poll < SPAWN_VERIFY_POLL_ATTEMPTS; poll++) {
+			const check = spawnSync("tmux", ["has-session", "-t", opts.sessionName]);
+			if (check.status === 0) return true;
+			if (poll < SPAWN_VERIFY_POLL_ATTEMPTS - 1) {
+				sleepSyncMs(SPAWN_VERIFY_POLL_INTERVAL_MS);
+			}
+		}
+		return false;
+	};
+
+	// Wait briefly for session to stabilize, then verify
+	sleepSyncMs(SPAWN_VERIFY_DELAY_MS);
+
+	// Derive the stderr log path for diagnostic messages (mirrors execution.ts convention)
+	const stderrLogHint = `${sidecarPath.replace(/\.jsonl$/, "-stderr.log")}`;
+
+	let spawnRetries = 0;
+	while (!verifySessionAlive() && spawnRetries < SPAWN_MAX_RETRIES) {
+		spawnRetries++;
+		console.error(`[task-runner] tmux: session '${opts.sessionName}' died on startup — retrying (${spawnRetries}/${SPAWN_MAX_RETRIES}). Stderr log: ${stderrLogHint}`);
+
+		// Brief delay before retry (increases with each attempt)
+		const retryDelay = spawnRetries * 500;
+		sleepSyncMs(retryDelay);
+
+		// Kill any remnant and re-create
+		spawnSync("tmux", ["kill-session", "-t", opts.sessionName]);
+
+		const retryResult = spawnSync("tmux", [
+			"new-session", "-d",
+			"-s", opts.sessionName,
+			wrappedCommand,
+		]);
+
+		if (retryResult.status !== 0) {
+			const retryStderr = retryResult.stderr?.toString().trim() || "unknown error";
+			console.error(`[task-runner] tmux: retry ${spawnRetries} session creation failed: ${retryStderr}`);
+			continue;
+		}
+
+		// Wait for the retried session to stabilize
+		sleepSyncMs(SPAWN_VERIFY_DELAY_MS);
+	}
+
+	if (spawnRetries > 0) {
+		const finalAlive = verifySessionAlive();
+		if (!finalAlive) {
+			cleanupTmp();
+			console.error(`[task-runner] tmux: session '${opts.sessionName}' failed after ${SPAWN_MAX_RETRIES} retries. Stderr log: ${stderrLogHint}`);
+			throw new Error(
+				`TMUX session '${opts.sessionName}' died on startup after ${SPAWN_MAX_RETRIES} retries. ` +
+				`Stderr log: ${stderrLogHint}`
+			);
+		}
+		console.error(`[task-runner] tmux: session '${opts.sessionName}' alive after ${spawnRetries} retry(ies)`);
+	}
+
 	console.error(`[task-runner] tmux: session '${opts.sessionName}' created (cwd: ${opts.cwd})`);
 
 
@@ -2452,11 +2582,9 @@ export default function (pi: ExtensionAPI) {
 								state.reviewerLastTool = delta.lastTool;
 							}
 
-							// Context % — prefer authoritative contextUsage (pi ≥ 0.63.0)
+							// Context % — authoritative contextUsage only (pi ≥ 0.63.0, TP-094)
 							if (delta.contextUsage) {
-								state.reviewerContextPct = delta.contextUsage.percentUsed;
-							} else if (delta.latestTotalTokens > 0 && contextWindow > 0) {
-								state.reviewerContextPct = (delta.latestTotalTokens / contextWindow) * 100;
+								state.reviewerContextPct = delta.contextUsage.percent;
 							}
 
 							writeLaneState(state);
@@ -2659,11 +2787,9 @@ export default function (pi: ExtensionAPI) {
 								state.reviewerCostUsd += delta.cost;
 								state.reviewerToolCount += delta.toolCalls;
 								if (delta.lastTool) state.reviewerLastTool = delta.lastTool;
-								// Context % — prefer authoritative contextUsage (pi ≥ 0.63.0)
+								// Context % — authoritative contextUsage only (pi ≥ 0.63.0, TP-094)
 								if (delta.contextUsage) {
-									state.reviewerContextPct = delta.contextUsage.percentUsed;
-								} else if (delta.latestTotalTokens > 0 && contextWindow > 0) {
-									state.reviewerContextPct = (delta.latestTotalTokens / contextWindow) * 100;
+									state.reviewerContextPct = delta.contextUsage.percent;
 								}
 								writeLaneState(state);
 								updateWidgets();
@@ -2814,8 +2940,35 @@ export default function (pi: ExtensionAPI) {
 				if (isStepComplete(ss)) completedBefore.add(ss.number);
 			}
 
+			// ── TP-095: Reset stale lane-state fields before new worker spawn (#333) ──
+			// When a worker crashes and restarts, the lane-state JSON retains stale
+			// values (workerStatus: "done", phase: "error", workerExitDiagnostic from
+			// the crash). Reset STATUS fields BEFORE the new worker spawns so the
+			// dashboard immediately reflects the new running state.
+			// IMPORTANT: Do NOT reset telemetry counters (tokens, cost) here — they
+			// accumulate across worker iterations via += in onTelemetry (#334).
+			if (state.totalIterations > 1) {
+				state.phase = "running";
+				state.workerStatus = "idle"; // Will be set to "running" by runWorker()
+				state.workerExitDiagnostic = null;
+				state.workerElapsed = 0;
+				state.workerContextPct = 0;
+				state.workerLastTool = "";
+				state.workerRetryActive = false;
+				state.workerRetryCount = 0;
+				state.workerLastRetryError = "";
+				// Note: workerToolCount, workerInputTokens, workerOutputTokens,
+				// workerCacheReadTokens, workerCacheWriteTokens, workerCostUsd
+				// are intentionally NOT reset — they persist across iterations.
+				writeLaneState(state);
+			}
+
 			await runWorker(remainingSteps, ctx);
 
+			// Write context % snapshot at iteration boundary (TP-094)
+			const { contextWindow: snapshotContextWindow } = resolveContextWindow(config, ctx);
+			writeContextSnapshot(state, snapshotContextWindow);
+
 			if (state.phase === "error") {
 				await shutdownPersistentReviewer("worker error");
 				return;
@@ -3220,7 +3373,10 @@ export default function (pi: ExtensionAPI) {
 		state.workerElapsed = 0;
 		state.workerContextPct = 0;
 		state.workerLastTool = "";
-		state.workerToolCount = 0;
+		// TP-095: Don't reset workerToolCount — accumulate across iterations (#334).
+		// Previous behavior zeroed the counter on each iteration, losing totals
+		// when a worker crashed and restarted. Token/cost counters already
+		// accumulate via += in onTelemetry and were never reset here.
 		state.workerRetryActive = false;
 		state.workerRetryCount = 0;
 		state.workerLastRetryError = "";
@@ -3248,6 +3404,8 @@ export default function (pi: ExtensionAPI) {
 		const warnPct = config.context.warn_percent;
 		const killPct = config.context.kill_percent;
 		console.error(`[task-runner] worker context window: ${contextWindow} (${contextWindowSource})`);
+		// One-shot warning when pi doesn't provide authoritative contextUsage (TP-094)
+		let warnedNoContextUsage = false;
 
 		if (spawnMode === "tmux") {
 			// ── TMUX mode ────────────────────────────────────────
@@ -3286,14 +3444,10 @@ export default function (pi: ExtensionAPI) {
 						state.workerLastRetryError = delta.lastRetryError;
 					}
 
-					// Context % — prefer authoritative contextUsage from pi ≥ 0.63.0,
-					// fall back to manual calculation from totalTokens + cacheRead.
-					{
-						const pct = delta.contextUsage
-							? delta.contextUsage.percentUsed
-							: (delta.latestTotalTokens > 0 && contextWindow > 0)
-								? (delta.latestTotalTokens / contextWindow) * 100
-								: 0;
+					// Context % — authoritative contextUsage only (pi ≥ 0.63.0, TP-094)
+					// Manual token-based fallback removed: avoids false thresholds on older pi.
+					if (delta.contextUsage) {
+						const pct = delta.contextUsage.percent;
 						if (pct > 0) {
 							state.workerContextPct = pct;
 							if (pct >= warnPct) {
@@ -3305,6 +3459,10 @@ export default function (pi: ExtensionAPI) {
 								spawned.kill();
 							}
 						}
+					} else if (delta.sawStatsResponseWithoutContextUsage && !warnedNoContextUsage) {
+						// One-shot warning: pi responded to get_session_stats but omitted contextUsage (older pi)
+						warnedNoContextUsage = true;
+						console.error(`[task-runner] warning: pi did not provide contextUsage — context pressure thresholds disabled`);
 					}
 
 					updateWidgets();

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,10 @@ export interface PostIntegrateCleanupResult {
 	mergeFilesDeleted: number;
 	/** Number of lane prompt files deleted */
 	promptFilesDeleted: number;
+	/** Number of mailbox batch directories deleted (0 or 1) */
+	mailboxDirsDeleted: number;
+	/** Number of context-snapshot batch directories deleted (0 or 1) */
+	snapshotDirsDeleted: number;
 	/** Warnings from non-fatal cleanup failures */
 	warnings: string[];
 }
@@ -57,6 +62,8 @@ export function cleanupPostIntegrate(stateRoot: string, batchId: string): PostIn
 		telemetryFilesDeleted: 0,
 		mergeFilesDeleted: 0,
 		promptFilesDeleted: 0,
+		mailboxDirsDeleted: 0,
+		snapshotDirsDeleted: 0,
 		warnings: [],
 	};
 
@@ -119,6 +126,28 @@ 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}`);
+		}
+	}
+
+	// ── Context snapshots directory (.pi/context-snapshots/{batchId}/) ──────
+	const snapshotBatchDir = join(stateRoot, ".pi", "context-snapshots", batchId);
+	if (existsSync(snapshotBatchDir)) {
+		try {
+			rmSync(snapshotBatchDir, { recursive: true, force: true });
+			result.snapshotDirsDeleted = 1;
+		} catch (err: unknown) {
+			result.warnings.push(`Failed to delete context-snapshots directory ${snapshotBatchDir}: ${(err as Error).message}`);
+		}
+	}
+
 	return result;
 }
 
@@ -127,13 +156,15 @@ 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 + result.snapshotDirsDeleted;
 
 	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`);
+		if (result.snapshotDirsDeleted > 0) segments.push(`${result.snapshotDirsDeleted} snapshots`);
 		parts.push(`🧹 Cleaned up ${totalDeleted} artifact file(s): ${segments.join(", ")}`);
 	}
 
@@ -155,6 +186,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 +231,7 @@ export function sweepStaleArtifacts(
 ): PreflightSweepResult {
 	const result: PreflightSweepResult = {
 		staleFilesDeleted: 0,
+		staleDirsDeleted: 0,
 		skipped: false,
 		warnings: [],
 	};
@@ -255,6 +289,35 @@ export function sweepStaleArtifacts(
 		(name.startsWith("merge-request-") && name.endsWith(".txt")),
 	);
 
+	// Sweep stale batch directories under a parent (mailbox, context-snapshots)
+	const sweepBatchDirs = (parentDir: string, label: string): void => {
+		if (!existsSync(parentDir)) return;
+		try {
+			const entries = readdirSync(parentDir);
+			for (const entry of entries) {
+				const entryPath = join(parentDir, 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 ${label} dir ${entry}: ${(err as Error).message}`);
+				}
+			}
+		} catch (err: unknown) {
+			result.warnings.push(`Failed to read ${label} directory ${parentDir}: ${(err as Error).message}`);
+		}
+	};
+
+	// Sweep stale mailbox batch directories (.pi/mailbox/{batchId}/)
+	sweepBatchDirs(join(stateRoot, ".pi", MAILBOX_DIR_NAME), "mailbox");
+
+	// Sweep stale context-snapshot batch directories (.pi/context-snapshots/{batchId}/)
+	sweepBatchDirs(join(stateRoot, ".pi", "context-snapshots"), "context-snapshots");
+
 	return result;
 }
 
@@ -265,12 +328,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 +462,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,
@@ -1086,18 +1088,6 @@ export async function executeOrchBatch(
 			continue;
 		}
 
-		onNotify(
-			ORCH_MESSAGES.orchWaveStart(waveIdx + 1, rawWaves.length, waveTasks.length, Math.min(waveTasks.length, orchConfig.orchestrator.max_lanes)),
-			"info",
-		);
-
-		// TP-040: Emit wave_start event
-		emitEvent(stateRoot, {
-			...buildEngineEventBase("wave_start", batchState.batchId, waveIdx, batchState.phase),
-			taskIds: waveTasks,
-			laneCount: Math.min(waveTasks.length, orchConfig.orchestrator.max_lanes),
-		}, onEngineEvent);
-
 		const handleWaveMonitorUpdate: MonitorUpdateCallback = (monitorState) => {
 			const changed = syncTaskOutcomesFromMonitor(monitorState, allTaskOutcomes);
 			if (changed) {
@@ -1110,6 +1100,17 @@ export async function executeOrchBatch(
 		const onLanesAllocatedCb = (lanes: AllocatedLane[]) => {
 			latestAllocatedLanes = lanes;
 			batchState.currentLanes = lanes;
+
+			// Emit wave_start with actual lane count (post-affinity grouping)
+			onNotify(
+				ORCH_MESSAGES.orchWaveStart(waveIdx + 1, rawWaves.length, waveTasks.length, lanes.length),
+				"info",
+			);
+			emitEvent(stateRoot, {
+				...buildEngineEventBase("wave_start", batchState.batchId, waveIdx, batchState.phase),
+				taskIds: waveTasks,
+				laneCount: lanes.length,
+			}, onEngineEvent);
 			// TP-029: Track repos from newly allocated lanes for cleanup coverage
 			for (const lane of lanes) {
 				const laneRepoRoot = resolveRepoRoot(lane.repoId, repoRoot, workspaceConfig);

package/extensions/taskplane/execution.ts

@@ -594,9 +594,26 @@ export function buildTmuxSpawnArgs(
 		piCommand = `${envParts} pi --no-session -e ${shellQuote(taskRunnerExtPath)}`;
 	}
 
-	// NOTE: Do not redirect lane output here. Shell redirection has proven
-	// fragile across Windows + tmux environments and can prevent session spawn.
-	// Diagnostics use tmux pane capture + STATUS tail in pollUntilTaskComplete().
+	// TP-095: Capture lane session stderr to a log file (#339).
+	// When the lane session (rpc-wrapper → pi → task-runner) dies, stderr is
+	// lost to tmux scrollback. Redirect stderr to a persistent log file
+	// co-located with telemetry so the supervisor can diagnose lane deaths.
+	//
+	// We append stderr to a file using `2>>`. This captures all stderr output
+	// from rpc-wrapper (which includes pi stderr forwarding, progress display,
+	// and crash diagnostics). The tmux pane loses live stderr visibility, but
+	// the dashboard provides live monitoring and the file preserves everything
+	// for post-mortem analysis.
+	//
+	// Appended to piCommand (not the tmux shell wrapper) to target the
+	// node/rpc-wrapper process specifically. This avoids the fragile shell
+	// redirection issues that previously caused spawn failures on Windows.
+	if (sidecarPath) {
+		// Derive stderr log path from sidecar path:
+		// .pi/telemetry/{basename}.jsonl → .pi/telemetry/{basename}-stderr.log
+		const stderrLogPath = sidecarPath.replace(/\.jsonl$/, "-stderr.log");
+		piCommand = `${piCommand} 2>> ${shellQuote(stderrLogPath)}`;
+	}
 
 	const tmuxWorktreePath = toTmuxPath(worktreePath);
 	const wrappedCommand = `cd ${shellQuote(tmuxWorktreePath)} && ${piCommand}`;