taskplane 0.22.12 → 0.22.14

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.
@@ -944,6 +972,16 @@ function logExecution(statusPath: string, action: string, outcome: string): void
 	appendTableRow(statusPath, "Execution Log", `| ${ts} | ${action} | ${outcome} |`);
 }
 
+/**
+ * TP-090: Sanitize steering message content for safe injection into a markdown table row.
+ * Collapses newlines to " / ", escapes pipe characters, and truncates to 200 chars.
+ */
+function sanitizeSteeringContent(content: string): string {
+	let s = content.replace(/\r?\n/g, " / ").replace(/\|/g, "\\|");
+	if (s.length > 200) s = s.slice(0, 197) + "...";
+	return s;
+}
+
 function logReview(statusPath: string, num: string, type: string, stepNum: number, verdict: string, file: string): void {
 	appendTableRow(statusPath, "Reviews", `| ${num} | ${type} | Step ${stepNum} | ${verdict} | ${file} |`);
 }
@@ -1371,7 +1409,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 +1430,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 +1546,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;
 			}
@@ -1532,6 +1577,68 @@ export const _resolveContextWindow = resolveContextWindow;
 export const _FALLBACK_CONTEXT_WINDOW = FALLBACK_CONTEXT_WINDOW;
 export type { SidecarTailState, SidecarTelemetryDelta };
 
+// ── Stable Sidecar Path Generation (TP-097) ─────────────────────────
+
+/**
+ * Generate a deterministic telemetry basename for sidecar/exit-summary files.
+ *
+ * The basename is stable per session (not per spawn attempt). When called
+ * once before the iteration loop and reused, it ensures that:
+ * - Crash recovery writes to the same sidecar file (tailing resumes)
+ * - Exit summaries overwrite the same file (latest wins)
+ *
+ * Naming contract:
+ *   {opId}-{batchId}-{repoId}[-{taskId}][-lane-{N}]-{role}
+ *
+ * @param sessionName — TMUX session name (e.g., "orch-lane-1-worker")
+ * @param taskId — Optional task ID for enrichment (e.g., "TP-097")
+ * @returns Object with sidecarPath and exitSummaryPath
+ */
+function generateStableSidecarPaths(sessionName: string, taskId?: string): {
+	sidecarPath: string;
+	exitSummaryPath: string;
+} {
+	// Resolve opId: same priority chain as naming.ts resolveOperatorId()
+	let opId = "op";
+	const envOpId = process.env.TASKPLANE_OPERATOR_ID;
+	if (envOpId?.trim()) {
+		opId = envOpId.trim().toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "").slice(0, 12) || "op";
+	} else {
+		try {
+			const username = userInfo().username;
+			if (username?.trim()) {
+				opId = username.trim().toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "").slice(0, 12) || "op";
+			}
+		} catch { /* userInfo() can throw on some platforms */ }
+	}
+
+	// Use ORCH_BATCH_ID if available (orchestrated mode), otherwise fallback to timestamp
+	const batchId = process.env.ORCH_BATCH_ID || String(Date.now());
+	const repoId = process.env.TASKPLANE_REPO_ID || "default";
+
+	// Extract role (worker/reviewer) from sessionName, and optional lane component
+	const role = sessionName.endsWith("-reviewer") ? "reviewer" : "worker";
+	const laneMatch = sessionName.match(/lane-(\d+)/);
+	const laneSuffix = laneMatch ? `-lane-${laneMatch[1]}` : "";
+
+	// Include taskId when available — sanitize to filesystem-safe characters
+	const taskIdSegment = taskId
+		? `-${taskId.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "").slice(0, 30)}`
+		: "";
+
+	const telemetryBasename = `${opId}-${batchId}-${repoId}${taskIdSegment}${laneSuffix}-${role}`;
+	const telemetryDir = join(getSidecarDir(), "telemetry");
+	if (!existsSync(telemetryDir)) mkdirSync(telemetryDir, { recursive: true });
+
+	return {
+		sidecarPath: join(telemetryDir, `${telemetryBasename}.jsonl`),
+		exitSummaryPath: join(telemetryDir, `${telemetryBasename}-exit.json`),
+	};
+}
+
+/** Expose for testing. */
+export const _generateStableSidecarPaths = generateStableSidecarPaths;
+
 // ── Exit Summary & Diagnostic ────────────────────────────────────────
 
 /**
@@ -1656,6 +1763,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.
@@ -1721,6 +1847,19 @@ function spawnAgentTmux(opts: {
 	 *  Enables the tmux poll loop to update TaskState (tokens, cost, context%, tools, retries)
 	 *  with the same signals that subprocess mode gets from onTokenUpdate/onContextPct/onToolCall. */
 	onTelemetry?: (delta: SidecarTelemetryDelta) => void;
+	/** TP-090: Path to .steering-pending JSONL flag file for STATUS.md annotation.
+	 *  Only set for worker sessions (not reviewer/merger). */
+	steeringPendingPath?: string;
+	/** TP-097: Caller-provided sidecar path for stable identity across iterations.
+	 *  When provided, spawnAgentTmux() skips internal path generation and uses this path.
+	 *  The caller (runWorker) generates this ONCE before the iteration loop. */
+	sidecarPath?: string;
+	/** TP-097: Caller-provided exit summary path (paired with sidecarPath). */
+	exitSummaryPath?: string;
+	/** TP-097: Caller-provided tail state for resuming sidecar tailing across iterations.
+	 *  When provided, the poll loop reuses this state instead of creating a fresh one.
+	 *  This ensures tailing resumes from the last byte position after crash recovery. */
+	tailState?: SidecarTailState;
 }): {
 	promise: Promise<{ output: string; exitCode: number; elapsed: number; killed: boolean }>;
 	kill: () => void;
@@ -1738,59 +1877,55 @@ function spawnAgentTmux(opts: {
 		);
 	}
 
-	// ── Generate telemetry file paths ───────────────────────────────
-	// Naming contract from resilience roadmap:
-	//   .pi/telemetry/{opId}-{batchId}-{repoId}[-{taskId}][-lane-{N}]-{role}.{ext}
-	//
-	// In standalone /task mode (no orchestrator):
-	//   opId    → TASKPLANE_OPERATOR_ID env, or OS username, or "op"
-	//   batchId → timestamp (no batch concept in standalone mode)
-	//   repoId  → "default" (single-repo mode)
-	//   taskId  → from opts.taskId when provided (e.g., "tp-026"), omitted if absent
-	//   lane    → omitted (no lanes)
-	//   role    → derived from sessionName suffix (worker/reviewer)
-	//
-	// getSidecarDir() respects ORCH_SIDECAR_DIR for workspace mode.
-	const telemetryTs = Date.now();
-
-	// Resolve opId: same priority chain as naming.ts resolveOperatorId()
-	let opId = "op";
-	const envOpId = process.env.TASKPLANE_OPERATOR_ID;
-	if (envOpId?.trim()) {
-		opId = envOpId.trim().toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "").slice(0, 12) || "op";
+	// ── Resolve telemetry file paths ───────────────────────────────
+	// TP-097: When the caller provides sidecarPath + exitSummaryPath, reuse them
+	// for stable identity across crash recovery iterations. Otherwise, generate
+	// paths internally (backward compatible for reviewer/quality-gate/standalone).
+	let sidecarPath: string;
+	let exitSummaryPath: string;
+	if (opts.sidecarPath && opts.exitSummaryPath) {
+		// TP-097: Caller provided stable paths (worker iteration flow)
+		sidecarPath = opts.sidecarPath;
+		exitSummaryPath = opts.exitSummaryPath;
 	} else {
-		try {
-			const username = userInfo().username;
-			if (username?.trim()) {
-				opId = username.trim().toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "").slice(0, 12) || "op";
-			}
-		} catch { /* userInfo() can throw on some platforms */ }
+		// Internal generation: use unique per-spawn paths (Date.now-based batchId)
+		// to prevent reviewer/QG sessions from replaying old telemetry on respawn.
+		// Only the worker iteration flow uses ORCH_BATCH_ID for stable identity.
+		const telemetryTs = Date.now();
+		let opId = "op";
+		const envOpId = process.env.TASKPLANE_OPERATOR_ID;
+		if (envOpId?.trim()) {
+			opId = envOpId.trim().toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "").slice(0, 12) || "op";
+		} else {
+			try {
+				const username = userInfo().username;
+				if (username?.trim()) {
+					opId = username.trim().toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "").slice(0, 12) || "op";
+				}
+			} catch { /* userInfo() can throw on some platforms */ }
+		}
+		const batchId = String(telemetryTs);
+		const repoId = "default";
+		const role = opts.sessionName.endsWith("-reviewer") ? "reviewer" : "worker";
+		const laneMatch = opts.sessionName.match(/lane-(\d+)/);
+		const laneSuffix = laneMatch ? `-lane-${laneMatch[1]}` : "";
+		const taskIdSegment = opts.taskId
+			? `-${opts.taskId.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "").slice(0, 30)}`
+			: "";
+		const telemetryBasename = `${opId}-${batchId}-${repoId}${taskIdSegment}${laneSuffix}-${role}`;
+		const internalTelemetryDir = join(getSidecarDir(), "telemetry");
+		if (!existsSync(internalTelemetryDir)) mkdirSync(internalTelemetryDir, { recursive: true });
+		sidecarPath = join(internalTelemetryDir, `${telemetryBasename}.jsonl`);
+		exitSummaryPath = join(internalTelemetryDir, `${telemetryBasename}-exit.json`);
 	}
-
-	const batchId = String(telemetryTs);
-	const repoId = "default";
-
-	// Extract role (worker/reviewer) from sessionName, and optional lane component
-	// sessionName patterns: "task-worker", "task-reviewer", "orch-lane-1-worker"
-	const role = opts.sessionName.endsWith("-reviewer") ? "reviewer" : "worker";
-	const laneMatch = opts.sessionName.match(/lane-(\d+)/);
-	const laneSuffix = laneMatch ? `-lane-${laneMatch[1]}` : "";
-
-	// Include taskId when available — sanitize to filesystem-safe characters.
-	// Pattern: {opId}-{batchId}-{repoId}[-{taskId}][-lane-{N}]-{role}
-	const taskIdSegment = opts.taskId
-		? `-${opts.taskId.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "").slice(0, 30)}`
-		: "";
-	const telemetryBasename = `${opId}-${batchId}-${repoId}${taskIdSegment}${laneSuffix}-${role}`;
-	const telemetryDir = join(getSidecarDir(), "telemetry");
+	// Ensure telemetry directory exists
+	const telemetryDir = dirname(sidecarPath);
 	if (!existsSync(telemetryDir)) mkdirSync(telemetryDir, { recursive: true });
-	const sidecarPath = join(telemetryDir, `${telemetryBasename}.jsonl`);
-	const exitSummaryPath = join(telemetryDir, `${telemetryBasename}-exit.json`);
 
 	// ── Write prompts to temp files ─────────────────────────────────
 	// Same pattern as spawnAgent() — avoids shell escaping issues with
 	// backticks, quotes, and special characters in markdown content.
-	const id = `${telemetryTs}-${Math.random().toString(36).slice(2, 8)}`;
+	const id = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 	const sysTmpFile = join(tmpdir(), `pi-task-sys-${id}.txt`);
 	const promptTmpFile = join(tmpdir(), `pi-task-prompt-${id}.txt`);
 	writeFileSync(sysTmpFile, opts.systemPrompt);
@@ -1844,6 +1979,10 @@ function spawnAgentTmux(opts: {
 		mkdirSync(join(mailboxDir, "inbox"), { recursive: true });
 		wrapperArgs.push("--mailbox-dir", quoteArg(mailboxDir));
 	}
+	// TP-090: Pass steering-pending path to rpc-wrapper (worker-only).
+	if (opts.steeringPendingPath) {
+		wrapperArgs.push("--steering-pending-path", quoteArg(opts.steeringPendingPath));
+	}
 	// 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("--");
@@ -1890,13 +2029,93 @@ 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.
+	// TP-097: Increased from 300→500ms and 2→5 retries for reliability (#335)
+	const SPAWN_VERIFY_DELAY_MS = 500;
+	const SPAWN_VERIFY_POLL_ATTEMPTS = 3;
+	const SPAWN_VERIFY_POLL_INTERVAL_MS = 200;
+	const SPAWN_MAX_RETRIES = 5;
+
+	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++;
+		// TP-097: Log stderr from the failed session for diagnostics
+		let failedStderr = "";
+		try {
+			if (existsSync(stderrLogHint)) {
+				const raw = readFileSync(stderrLogHint, "utf-8");
+				// Take last 500 chars to capture the most recent error
+				failedStderr = raw.length > 500 ? "..." + raw.slice(-500) : raw;
+			}
+		} catch { /* best effort */ }
+		console.error(`[task-runner] tmux: session '${opts.sessionName}' died on startup — retrying (${spawnRetries}/${SPAWN_MAX_RETRIES}).${failedStderr ? ` Last stderr: ${failedStderr.trim().slice(0, 200)}` : ""} Stderr log: ${stderrLogHint}`);
+
+		// Brief delay before retry (increases with each attempt: 500ms, 1000ms, 1500ms, ...)
+		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})`);
 
 
 	// ── Poll until session ends ─────────────────────────────────────
 	let killed = false;
 	const startTime = Date.now();
-	const tailState = createSidecarTailState();
+	// TP-097: Reuse caller-provided tailState for cross-iteration tailing resume.
+	// When the caller (runWorker) passes tailState, byte offset is preserved
+	// across iterations so tailing resumes from the last position after crash recovery.
+	const tailState = opts.tailState ?? createSidecarTailState();
 
 	const promise = (async (): Promise<{ output: string; exitCode: number; elapsed: number; killed: boolean }> => {
 		try {
@@ -1938,10 +2157,12 @@ function spawnAgentTmux(opts: {
 			};
 		}
 
-		// Normal completion — clean up temp files
+		// Normal completion — clean up temp files and orphan processes
 		const elapsed = Date.now() - startTime;
 		console.error(`[task-runner] tmux: session '${opts.sessionName}' ended after ${Math.round(elapsed / 1000)}s${killed ? " (killed)" : ""}`);
 		cleanupTmp();
+		// TP-097: Clean up orphan rpc-wrapper/pi processes after session ends
+		cleanupOrphanProcesses(sidecarPath);
 		console.error(`[task-runner] tmux: cleanup done for '${opts.sessionName}'`);
 		return {
 			output: "",      // No captured output in TMUX mode
@@ -1960,6 +2181,8 @@ function spawnAgentTmux(opts: {
 			// Session may have already exited — not an error
 			console.error(`[task-runner] tmux: session '${opts.sessionName}' already exited (kill was no-op)`);
 		}
+		// TP-097: Clean up orphan rpc-wrapper/pi processes on explicit kill
+		cleanupOrphanProcesses(sidecarPath);
 		cleanupTmp();
 		console.error(`[task-runner] tmux: cleanup done for '${opts.sessionName}' (killed)`);
 	};
@@ -1967,6 +2190,68 @@ function spawnAgentTmux(opts: {
 	return { promise, kill, sidecarPath, exitSummaryPath };
 }
 
+// ── Orphan Process Cleanup (TP-097) ───────────────────────────────────
+
+/**
+ * Read the PID file written by rpc-wrapper.mjs and kill orphan processes.
+ *
+ * The PID file is at `{sidecarPath}.pid` and contains JSON with wrapperPid
+ * and childPid fields. After a tmux session ends, the rpc-wrapper child
+ * process may still be alive (e.g., if the tmux session was killed externally
+ * or the wrapper didn't get a clean shutdown signal).
+ *
+ * Best-effort: failures are logged but never throw.
+ *
+ * @param sidecarPath - Path to the sidecar JSONL file (PID file is at sidecarPath + ".pid")
+ */
+function cleanupOrphanProcesses(sidecarPath: string): void {
+	const pidFilePath = sidecarPath + ".pid";
+	try {
+		if (!existsSync(pidFilePath)) return;
+
+		const raw = readFileSync(pidFilePath, "utf-8").trim();
+		if (!raw) return;
+
+		const pidData = JSON.parse(raw);
+		const pidsToCheck = new Set<number>();
+		if (typeof pidData.childPid === "number" && pidData.childPid > 0) {
+			pidsToCheck.add(pidData.childPid);
+		}
+		if (typeof pidData.wrapperPid === "number" && pidData.wrapperPid > 0) {
+			pidsToCheck.add(pidData.wrapperPid);
+		}
+
+		// Safety: never kill ourselves or PID 1 (init)
+		const selfPid = process.pid;
+		pidsToCheck.delete(selfPid);
+		pidsToCheck.delete(1);
+
+		for (const pid of pidsToCheck) {
+			try {
+				// Check if process is still alive (signal 0 = no-op, just check existence)
+				process.kill(pid, 0);
+				// Process is alive — send SIGTERM
+				console.error(`[task-runner] TP-097: killing orphan process PID ${pid}`);
+				try {
+					process.kill(pid, "SIGTERM");
+				} catch (killErr: any) {
+					console.error(`[task-runner] TP-097: failed to kill PID ${pid}: ${killErr?.message}`);
+				}
+			} catch {
+				// Process already dead — expected path
+			}
+		}
+
+		// Clean up the PID file
+		try { unlinkSync(pidFilePath); } catch {}
+	} catch (err: any) {
+		console.error(`[task-runner] TP-097: orphan cleanup error: ${err?.message}`);
+	}
+}
+
+/** Expose for testing. */
+export const _cleanupOrphanProcesses = cleanupOrphanProcesses;
+
 // ── Display Helpers ──────────────────────────────────────────────────
 
 function displayName(name: string): string {
@@ -2461,11 +2746,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);
@@ -2668,11 +2951,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();
@@ -2749,7 +3030,14 @@ export default function (pi: ExtensionAPI) {
 
 		updateStatusField(statusPath, "Status", "🟡 In Progress");
 		updateStatusField(statusPath, "Last Updated", new Date().toISOString().slice(0, 10));
-		logExecution(statusPath, "Task started", "Extension-driven execution");
+
+		// TP-098: Distinguish first start from restart/resume to prevent
+		// duplicate "Task started" entries in the execution log (#348).
+		if (state.totalIterations === 0) {
+			logExecution(statusPath, "Task started", "Extension-driven execution");
+		} else {
+			logExecution(statusPath, "Task resumed", `Resuming from iteration ${state.totalIterations}`);
+		}
 
 		// ── Per-task worker loop ─────────────────────────────────────
 		// Spawn one worker per iteration; each worker handles ALL remaining
@@ -2766,10 +3054,14 @@ export default function (pi: ExtensionAPI) {
 				const ss = currentStatus.steps.find(s => s.number === step.number);
 				if (ss?.status === "complete") continue;
 
-				if (!foundFirstIncomplete) {
+					if (!foundFirstIncomplete) {
 					// Mark the first incomplete step as in-progress
-					updateStepStatus(statusPath, step.number, "in-progress");
-					logExecution(statusPath, `Step ${step.number} started`, step.name);
+					// TP-098: Only log "Step N started" if the step was not already
+					// in-progress, preventing duplicate entries on restart (#348).
+					if (ss?.status !== "in-progress") {
+						updateStepStatus(statusPath, step.number, "in-progress");
+						logExecution(statusPath, `Step ${step.number} started`, step.name);
+					}
 					foundFirstIncomplete = true;
 				} else {
 					// Ensure future steps show as not-started, not in-progress
@@ -2788,11 +3080,26 @@ export default function (pi: ExtensionAPI) {
 			return ss.totalChecked === ss.totalItems && ss.totalItems > 0;
 		}
 
+		// ── TP-097: Generate stable sidecar paths ONCE before the iteration loop ──
+		// These paths are reused across all worker iterations so that:
+		// 1. After crash recovery, the new worker writes to the SAME sidecar file
+		// 2. tailState preserves byte offset, so tailing resumes from last position
+		// 3. Exit summary overwrites the same file (latest iteration wins)
+		const spawnMode = getSpawnMode(config);
+		let workerStableSidecar: { sidecarPath: string; exitSummaryPath: string } | null = null;
+		let workerTailState: SidecarTailState | null = null;
+		if (spawnMode === "tmux") {
+			const sessionName = `${getTmuxPrefix()}-worker`;
+			workerStableSidecar = generateStableSidecarPaths(sessionName, task.taskId);
+			workerTailState = createSidecarTailState();
+			console.error(`[task-runner] TP-097: stable sidecar path: ${workerStableSidecar.sidecarPath}`);
+		}
+
 		let noProgressCount = 0;
 		for (let iter = 0; iter < config.context.max_worker_iterations; iter++) {
 			if (state.phase === "paused") {
-				logExecution(statusPath, "Paused", `User paused at iteration ${iter + 1}`);
-				ctx.ui.notify(`Task paused at iteration ${iter + 1}`, "info");
+				logExecution(statusPath, "Paused", `User paused at iteration ${state.totalIterations}`);
+				ctx.ui.notify(`Task paused at iteration ${state.totalIterations}`, "info");
 				await shutdownPersistentReviewer("task paused");
 				return;
 			}
@@ -2823,7 +3130,61 @@ export default function (pi: ExtensionAPI) {
 				if (isStepComplete(ss)) completedBefore.add(ss.number);
 			}
 
-			await runWorker(remainingSteps, ctx);
+			// ── 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, workerStableSidecar, workerTailState);
+
+			// Write context % snapshot at iteration boundary (TP-094)
+			const { contextWindow: snapshotContextWindow } = resolveContextWindow(config, ctx);
+			writeContextSnapshot(state, snapshotContextWindow);
+
+			// ── TP-090: Annotate STATUS.md with delivered steering messages ──
+			// Check for .steering-pending JSONL flag written by rpc-wrapper.
+			// Must happen BEFORE the error-return so messages are not dropped.
+			const steeringFlagPath = join(task.taskFolder, ".steering-pending");
+			try {
+				if (existsSync(steeringFlagPath)) {
+					const raw = readFileSync(steeringFlagPath, "utf-8");
+					const lines = raw.split("\n").filter(l => l.trim());
+					for (const line of lines) {
+						try {
+							const entry = JSON.parse(line) as { ts: number; content: string; id: string };
+							const sanitized = sanitizeSteeringContent(entry.content);
+							// Use the delivered message timestamp, not current time
+							const ts = new Date(entry.ts).toISOString().slice(0, 16).replace("T", " ");
+							appendTableRow(statusPath, "Execution Log", `| ${ts} | \u26a0\ufe0f Steering | ${sanitized} |`);
+							console.error(`[task-runner] steering message annotated: ${entry.id}`);
+						} catch {
+							// Skip malformed JSONL lines
+						}
+					}
+					unlinkSync(steeringFlagPath);
+				}
+			} catch (err: any) {
+				// Non-fatal: steering annotation is supplementary
+				console.error(`[task-runner] steering-pending annotation error: ${err?.message || err}`);
+			}
 
 			if (state.phase === "error") {
 				await shutdownPersistentReviewer("worker error");
@@ -2838,8 +3199,10 @@ export default function (pi: ExtensionAPI) {
 			const progressDelta = afterTotalChecked - prevTotalChecked;
 			if (progressDelta <= 0) {
 				noProgressCount++;
-				logExecution(statusPath, "No progress", `Iteration ${iter + 1}: 0 new checkboxes (${noProgressCount}/${config.context.no_progress_limit} stall limit)`);
-				ctx.ui.notify(`⚠️ No progress in iteration ${iter + 1} (${noProgressCount}/${config.context.no_progress_limit})`, "warning");
+				// TP-098: Use state.totalIterations (global) instead of iter+1
+				// (loop-local) to avoid label collision across restarts (#348).
+				logExecution(statusPath, "No progress", `Iteration ${state.totalIterations}: 0 new checkboxes (${noProgressCount}/${config.context.no_progress_limit} stall limit)`);
+				ctx.ui.notify(`⚠️ No progress in iteration ${state.totalIterations} (${noProgressCount}/${config.context.no_progress_limit})`, "warning");
 				if (noProgressCount >= config.context.no_progress_limit) {
 					logExecution(statusPath, "Task blocked", `No progress after ${noProgressCount} iterations`);
 					ctx.ui.notify(`⚠️ Task blocked — no progress after ${noProgressCount} iterations`, "error");
@@ -2886,11 +3249,13 @@ export default function (pi: ExtensionAPI) {
 			// Log iteration summary with progress delta and completed steps
 			const completedNames = newlyCompleted.map(s => `Step ${s.number}`).join(", ");
 			if (newlyCompleted.length > 0) {
-				logExecution(statusPath, `Iteration ${iter + 1} summary`, `+${progressDelta} checkboxes, completed: ${completedNames}`);
-				ctx.ui.notify(`Iteration ${iter + 1}: completed ${completedNames} (+${progressDelta} checkboxes)`, "info");
+				// TP-098: Use state.totalIterations (global) instead of iter+1
+				// (loop-local) to avoid label collision across restarts (#348).
+				logExecution(statusPath, `Iteration ${state.totalIterations} summary`, `+${progressDelta} checkboxes, completed: ${completedNames}`);
+				ctx.ui.notify(`Iteration ${state.totalIterations}: completed ${completedNames} (+${progressDelta} checkboxes)`, "info");
 			} else if (progressDelta > 0) {
-				logExecution(statusPath, `Iteration ${iter + 1} summary`, `+${progressDelta} checkboxes, no steps fully completed`);
-				ctx.ui.notify(`Iteration ${iter + 1}: +${progressDelta} checkboxes (no steps fully completed)`, "info");
+				logExecution(statusPath, `Iteration ${state.totalIterations} summary`, `+${progressDelta} checkboxes, no steps fully completed`);
+				ctx.ui.notify(`Iteration ${state.totalIterations}: +${progressDelta} checkboxes (no steps fully completed)`, "info");
 			}
 
 			// Reviews are now driven inline by the worker via the review_step
@@ -3113,25 +3478,29 @@ export default function (pi: ExtensionAPI) {
 
 	// ── Worker ───────────────────────────────────────────────────────
 
-	async function runWorker(remainingSteps: StepInfo[], ctx: ExtensionContext): Promise<void> {
+	/** Pre-generated sidecar paths for stable identity across iterations (TP-097). */
+	type StableSidecarPaths = { sidecarPath: string; exitSummaryPath: string };
+
+	async function runWorker(
+		remainingSteps: StepInfo[],
+		ctx: ExtensionContext,
+		stableSidecar?: StableSidecarPaths | null,
+		sharedTailState?: SidecarTailState | null,
+	): Promise<void> {
 		if (!state.task || !state.config) return;
 
 		const task = state.task;
 		const config = state.config;
 		const statusPath = join(task.taskFolder, "STATUS.md");
 		const wrapUpFile = join(task.taskFolder, ".task-wrap-up");
-		const legacyWrapUpFile = join(task.taskFolder, ".wiggum-wrap-up");
 
 		const clearWrapUpSignals = () => {
 			if (existsSync(wrapUpFile)) try { unlinkSync(wrapUpFile); } catch {}
-			if (existsSync(legacyWrapUpFile)) try { unlinkSync(legacyWrapUpFile); } catch {}
 		};
 
 		const writeWrapUpSignal = (reason: string) => {
 			const msg = `${reason} at ${new Date().toISOString()}`;
 			if (!existsSync(wrapUpFile)) writeFileSync(wrapUpFile, msg);
-			// Backward compatibility: write legacy signal too until all workers migrate.
-			if (!existsSync(legacyWrapUpFile)) writeFileSync(legacyWrapUpFile, msg);
 		};
 
 		clearWrapUpSignals();
@@ -3219,8 +3588,8 @@ export default function (pi: ExtensionAPI) {
 			`5. Check for wrap-up signal files before starting the next step`,
 			`6. Proceed to the next incomplete step`,
 			``,
-			`Wrap-up signal files: ${wrapUpFile} (primary), ${legacyWrapUpFile} (legacy)`,
-			`Check for either file after each checkpoint. If one exists, stop.`,
+			`Wrap-up signal file: ${wrapUpFile}`,
+			`Check for this file after each checkpoint. If it exists, stop.`,
 			archiveSuppression,
 			contextDocsList,
 		].join("\n");
@@ -3229,7 +3598,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 = "";
@@ -3257,6 +3629,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 ────────────────────────────────────────
@@ -3265,6 +3639,12 @@ export default function (pi: ExtensionAPI) {
 			// Kill via wall-clock timeout (context-% wrap-up also available via sidecar).
 			const sessionName = `${getTmuxPrefix()}-worker`;
 
+			// TP-090: Construct .steering-pending path for worker-only STATUS.md annotation.
+			// Only set when running under orchestrator (mailbox is orch-only).
+			const steeringPendingPath = isOrchestratedMode()
+				? join(task.taskFolder, ".steering-pending")
+				: undefined;
+
 			const spawned = spawnAgentTmux({
 				sessionName,
 				cwd: ctx.cwd,
@@ -3274,6 +3654,11 @@ export default function (pi: ExtensionAPI) {
 				tools: config.worker.tools || workerDef?.tools || "read,write,edit,bash,grep,find,ls",
 				thinking: config.worker.thinking || "off",
 				taskId: task.taskId,
+				steeringPendingPath,
+				// TP-097: Pass stable sidecar paths and shared tailState for cross-iteration identity
+				sidecarPath: stableSidecar?.sidecarPath,
+				exitSummaryPath: stableSidecar?.exitSummaryPath,
+				tailState: sharedTailState ?? undefined,
 				onTelemetry: (delta) => {
 					// Accumulate tokens and cost (same as subprocess onTokenUpdate)
 					state.workerInputTokens += delta.inputTokens;
@@ -3295,14 +3680,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) {
@@ -3314,6 +3695,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();