taskplane 0.22.13 → 0.22.14

package/bin/rpc-wrapper.mjs

@@ -28,7 +28,7 @@
  */
 
 import { spawn } from "node:child_process";
-import { readFileSync, writeFileSync, appendFileSync, mkdirSync, readdirSync, renameSync } from "node:fs";
+import { readFileSync, writeFileSync, appendFileSync, mkdirSync, readdirSync, renameSync, unlinkSync } from "node:fs";
 import { dirname, resolve, join, basename } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 
@@ -46,6 +46,7 @@ function parseArgs(argv) {
 		passthrough: [],
 		help: false,
 		mailboxDir: null,
+		steeringPendingPath: null,
 	};
 
 	let i = 2; // skip "node" and script path
@@ -78,6 +79,9 @@ function parseArgs(argv) {
 		} else if (arg === "--mailbox-dir" && i + 1 < argv.length) {
 			args.mailboxDir = argv[++i];
 			i++;
+		} else if (arg === "--steering-pending-path" && i + 1 < argv.length) {
+			args.steeringPendingPath = argv[++i];
+			i++;
 		} else if (arg === "--") {
 			args.passthrough = argv.slice(i + 1);
 			break;
@@ -108,6 +112,7 @@ Optional:
   --tools <t1,t2,...>          Comma-separated tool names
   --extensions <e1,e2,...>     Comma-separated extension paths
   --mailbox-dir <path>         Mailbox directory for agent steering (TP-089)
+  --steering-pending-path <p>  Path to .steering-pending JSONL flag file (TP-090)
   -h, --help                   Show this help
 `
 	);
@@ -509,9 +514,10 @@ const MAILBOX_MESSAGE_TYPES = new Set(["steer", "query", "abort", "info", "reply
  *
  * @param {string} mailboxDir - Session mailbox directory (e.g., .pi/mailbox/{batchId}/{session})
  * @param {object} proc - The spawned pi process (must have writable stdin)
+ * @param {string|null} steeringPendingPath - Path to .steering-pending JSONL flag file (TP-090, worker-only)
  * @returns {{ delivered: number, skipped: number }} Delivery stats
  */
-function checkMailboxAndSteer(mailboxDir, proc) {
+function checkMailboxAndSteer(mailboxDir, proc, steeringPendingPath) {
 	const stats = { delivered: 0, skipped: 0 };
 
 	// Derive expected values from path structure:
@@ -616,6 +622,17 @@ function checkMailboxAndSteer(mailboxDir, proc) {
 
 			stats.delivered++;
 			process.stderr.write(`\n[STEERING] Delivered message ${message.id}\n`);
+
+			// TP-090: Append to .steering-pending JSONL flag for task-runner STATUS.md annotation.
+			// Worker-only: steeringPendingPath is only set for worker sessions.
+			if (steeringPendingPath) {
+				try {
+					const entry = JSON.stringify({ ts: message.timestamp, content: message.content, id: message.id }) + "\n";
+					appendFileSync(steeringPendingPath, entry, "utf-8");
+				} catch (err) {
+					process.stderr.write(`\n[STEERING] WARNING: failed to write .steering-pending: ${err.message}\n`);
+				}
+			}
 		} catch (err) {
 			process.stderr.write(`\n[STEERING] WARNING: failed to deliver ${filename}: ${err.message}\n`);
 			stats.skipped++;
@@ -759,6 +776,29 @@ const proc = spawn("pi", piArgs, {
 	shell: true, // Required for Windows: resolves pi.cmd shim. Matches task-runner.ts pattern.
 });
 
+// ── TP-097: Write PID file for orphan cleanup ──────────────────
+// Write both the wrapper PID and the pi child PID alongside the sidecar file.
+// The task-runner reads this on session end to kill orphan processes.
+// Format: JSON with wrapperPid and childPid fields.
+const pidFilePath = args.sidecarPath + ".pid";
+try {
+	const pidData = {
+		wrapperPid: process.pid,
+		childPid: proc.pid ?? null,
+		startedAt: Date.now(),
+	};
+	writeFileSync(pidFilePath, JSON.stringify(pidData) + "\n", "utf-8");
+	process.stderr.write(`[rpc-wrapper] PID file written: ${pidFilePath} (wrapper=${process.pid}, child=${proc.pid})\n`);
+} catch (err) {
+	process.stderr.write(`[rpc-wrapper] WARNING: failed to write PID file: ${err.message}\n`);
+}
+
+// Clean up PID file on process exit (best-effort)
+function cleanupPidFile() {
+	try { unlinkSync(pidFilePath); } catch { /* ignore */ }
+}
+process.on("exit", cleanupPidFile);
+
 // ── Send prompt via JSONL stdin ──────────────────────────────────────
 
 const promptCmd = { type: "prompt", message: promptContent };
@@ -852,7 +892,7 @@ function handleEvent(event) {
 			// Only active when --mailbox-dir is provided (backward compatible).
 			if (args.mailboxDir) {
 				try {
-					checkMailboxAndSteer(args.mailboxDir, proc);
+					checkMailboxAndSteer(args.mailboxDir, proc, args.steeringPendingPath || null);
 				} catch (err) {
 					// Never crash on mailbox I/O errors
 					process.stderr.write(`\n[STEERING] ERROR: ${err.message}\n`);

package/extensions/task-runner.ts

@@ -972,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} |`);
 }
@@ -1567,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 ────────────────────────────────────────
 
 /**
@@ -1775,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;
@@ -1792,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);
@@ -1898,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("--");
@@ -1948,10 +2033,11 @@ function spawnAgentTmux(opts: {
 	// 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;
+	// 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 = 2;
+	const SPAWN_MAX_RETRIES = 5;
 
 	const verifySessionAlive = (): boolean => {
 		for (let poll = 0; poll < SPAWN_VERIFY_POLL_ATTEMPTS; poll++) {
@@ -1973,9 +2059,18 @@ function spawnAgentTmux(opts: {
 	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}`);
+		// 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)
+		// Brief delay before retry (increases with each attempt: 500ms, 1000ms, 1500ms, ...)
 		const retryDelay = spawnRetries * 500;
 		sleepSyncMs(retryDelay);
 
@@ -2017,7 +2112,10 @@ function spawnAgentTmux(opts: {
 	// ── 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 {
@@ -2059,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
@@ -2081,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)`);
 	};
@@ -2088,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 {
@@ -2866,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
@@ -2883,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
@@ -2905,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;
 			}
@@ -2963,12 +3153,39 @@ export default function (pi: ExtensionAPI) {
 				writeLaneState(state);
 			}
 
-			await runWorker(remainingSteps, ctx);
+			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");
 				return;
@@ -2982,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");
@@ -3030,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
@@ -3257,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();
@@ -3363,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");
@@ -3414,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,
@@ -3423,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;

package/extensions/taskplane/abort.ts

@@ -148,9 +148,8 @@ export function planAbortActions(
 /**
  * Write wrap-up signal files to each lane's task folder.
  *
- * Writes both `.task-wrap-up` (primary) and `.wiggum-wrap-up` (legacy)
- * for backward compatibility. Continues on partial failure — aggregates
- * errors per lane.
+ * Writes `.task-wrap-up` signal file to each lane's task folder.
+ * Continues on partial failure — aggregates errors per lane.
  *
  * @param targets   - Target sessions with resolved task folders
  * @returns Updated target results with wrapUpWritten/wrapUpError
@@ -176,7 +175,6 @@ export function writeWrapUpFiles(
 
 		try {
 			const primaryPath = join(target.taskFolderInWorktree, ".task-wrap-up");
-			const legacyPath = join(target.taskFolderInWorktree, ".wiggum-wrap-up");
 
 			// Ensure directory exists
 			if (!existsSync(target.taskFolderInWorktree)) {
@@ -185,7 +183,6 @@ export function writeWrapUpFiles(
 			}
 
 			writeFileSync(primaryPath, content, "utf-8");
-			writeFileSync(legacyPath, content, "utf-8");
 			results.push({ sessionName: target.sessionName, written: true, error: null });
 		} catch (err) {
 			results.push({

package/extensions/taskplane/merge.ts

@@ -2,7 +2,7 @@
  * Merge orchestration, merge agents, merge worktree
  * @module orch/merge
  */
-import { readFileSync, writeFileSync, existsSync, unlinkSync, copyFileSync, mkdirSync, rmSync } from "fs";
+import { readFileSync, writeFileSync, existsSync, unlinkSync, copyFileSync, mkdirSync, rmSync, readdirSync } from "fs";
 import { readFile as fsReadFile } from "fs/promises";
 import { execSync, spawnSync } from "child_process";
 import { join, dirname, resolve, relative } from "path";
@@ -1841,16 +1841,48 @@ export async function mergeWave(
 	// ── Stage workspace task artifacts into merge worktree ──────────
 	// TP-035: Tightened artifact staging — only allowlisted task-owned files
 	// are staged. The allowlist is derived per-task-folder from completed lanes:
-	// exactly `.DONE`, `STATUS.md`, and `REVIEW_VERDICT.json` (when present).
+	// `.DONE`, `STATUS.md`, `REVIEW_VERDICT.json`, and `.reviews/**` files.
 	// Files outside known task folders, worktree internals, and repo-escape
 	// paths are rejected. Uses resolve+relative path containment consistent
 	// with ensureTaskFilesCommitted() in execution.ts.
 	if (mergeWorkDir) {
 		// Build the set of allowed artifact paths (repo-root-relative) from
 		// the completed lanes' task folders.
+		//
+		// Allowlist policy:
+		// - task marker files: .DONE, STATUS.md, REVIEW_VERDICT.json
+		// - review outputs under task-local .reviews/**
 		const ALLOWED_ARTIFACT_NAMES = [".DONE", "STATUS.md", "REVIEW_VERDICT.json"];
+		const ALLOWED_ARTIFACT_DIRS = [".reviews"];
 		const resolvedRepoRoot = resolve(repoRoot);
 		const allowedRelPaths = new Set<string>();
+		const relPathToWorktree = new Map<string, string>();
+
+		const listFilesRecursively = (rootDir: string): string[] => {
+			if (!existsSync(rootDir)) return [];
+			const files: string[] = [];
+			const walk = (dir: string): void => {
+				let entries;
+				try {
+					entries = readdirSync(dir, { withFileTypes: true });
+				} catch {
+					return;
+				}
+				for (const entry of entries) {
+					const absPath = join(dir, entry.name);
+					if (entry.isDirectory()) {
+						walk(absPath);
+						continue;
+					}
+					if (!entry.isFile()) continue;
+					const relPath = relative(rootDir, absPath).replace(/\\/g, "/");
+					if (!relPath || relPath.startsWith("..") || relPath.startsWith("/")) continue;
+					files.push(relPath);
+				}
+			};
+			walk(rootDir);
+			return files;
+		};
 
 		for (const lane of orderedLanes) {
 			for (const allocTask of lane.tasks) {
@@ -1867,7 +1899,24 @@ export async function mergeWave(
 				}
 
 				for (const name of ALLOWED_ARTIFACT_NAMES) {
-					allowedRelPaths.add(`${relFolder}/${name}`);
+					const rp = `${relFolder}/${name}`;
+					allowedRelPaths.add(rp);
+					relPathToWorktree.set(rp, join(lane.worktreePath, rp));
+				}
+
+				for (const dirName of ALLOWED_ARTIFACT_DIRS) {
+					const laneDir = join(lane.worktreePath, relFolder, dirName);
+					for (const relFile of listFilesRecursively(laneDir)) {
+						const rp = `${relFolder}/${dirName}/${relFile}`;
+						allowedRelPaths.add(rp);
+						relPathToWorktree.set(rp, join(lane.worktreePath, rp));
+					}
+
+					const repoDir = join(repoRoot, relFolder, dirName);
+					for (const relFile of listFilesRecursively(repoDir)) {
+						const rp = `${relFolder}/${dirName}/${relFile}`;
+						allowedRelPaths.add(rp);
+					}
 				}
 			}
 		}
@@ -1875,12 +1924,44 @@ export async function mergeWave(
 		if (allowedRelPaths.size > 0) {
 			let staged = 0;
 			let skipped = 0;
+			let preserved = 0;
 
 			for (const relPath of allowedRelPaths) {
-				const srcPath = join(repoRoot, relPath);
-				if (!existsSync(srcPath)) continue; // File not present (e.g., no REVIEW_VERDICT.json) — skip silently
-
 				const destPath = join(mergeWorkDir, relPath);
+
+				// TP-099: If the file already exists in mergeWorkDir (from lane merge),
+				// do NOT overwrite it — the lane merge brought the correct worker-updated
+				// version (e.g., STATUS.md with checked items, execution log, discoveries).
+				// Overwriting from repoRoot would revert to the pre-execution template.
+				if (existsSync(destPath)) {
+					preserved++;
+					continue;
+				}
+
+				// File missing from mergeWorkDir — backfill from best available source.
+				// Primary: lane worktree (has worker-generated .DONE/STATUS/.reviews content).
+				// Fallback: repoRoot (original task folder, with path containment check).
+				const worktreeSrc = relPathToWorktree.get(relPath);
+				let srcPath: string | null = null;
+
+				// Try lane worktree first (trusted engine-allocated path)
+				if (worktreeSrc && existsSync(worktreeSrc)) {
+					srcPath = worktreeSrc;
+				} else {
+					// Fallback to repoRoot with path containment check (TP-035 hardening)
+					const repoRootSrc = join(repoRoot, relPath);
+					if (existsSync(repoRootSrc)) {
+						const resolvedSrc = resolve(repoRootSrc);
+						const srcRelToRepo = relative(resolvedRepoRoot, resolvedSrc).replace(/\\/g, "/");
+						if (srcRelToRepo.startsWith("..") || srcRelToRepo.startsWith("/")) {
+							execLog("merge", `W${waveIndex}`, `skipping artifact source outside repo root`, { path: relPath, src: repoRootSrc });
+							continue;
+						}
+						srcPath = repoRootSrc;
+					}
+				}
+				if (!srcPath) continue; // File not present anywhere — skip silently
+
 				try {
 					mkdirSync(dirname(destPath), { recursive: true });
 					copyFileSync(srcPath, destPath);
@@ -1894,13 +1975,14 @@ export async function mergeWave(
 			}
 
 			if (staged > 0) {
-				spawnSync("git", ["commit", "-m", `checkpoint: wave ${waveIndex} task artifacts (.DONE, STATUS.md, REVIEW_VERDICT.json)`], { cwd: mergeWorkDir });
+				spawnSync("git", ["commit", "-m", `checkpoint: wave ${waveIndex} task artifacts (.DONE, STATUS.md, REVIEW_VERDICT.json, .reviews/*)`], { cwd: mergeWorkDir });
 				execLog("merge", `W${waveIndex}`, `committed ${staged} task artifact(s) to merge worktree`, {
 					skipped,
+					preserved,
 					allowedCandidates: allowedRelPaths.size,
 				});
 			} else {
-				execLog("merge", `W${waveIndex}`, `no task artifacts to stage (0 of ${allowedRelPaths.size} candidates present/changed)`);
+				execLog("merge", `W${waveIndex}`, `no task artifacts to stage (0 of ${allowedRelPaths.size} candidates present/changed, ${preserved} preserved from lane merge)`);
 			}
 
 			// Keep both .DONE and STATUS.md in develop's working tree:

package/package.json

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

package/templates/agents/task-worker.md

@@ -53,12 +53,11 @@ edit STATUS.md
 
 Then **check for wrap-up signal:**
 ```bash
-if test -f "<TASK_FOLDER>/.task-wrap-up" || test -f "<TASK_FOLDER>/.wiggum-wrap-up"; then
+if test -f "<TASK_FOLDER>/.task-wrap-up"; then
   echo "WRAP_UP_SIGNAL"
 fi
 ```
-Primary signal file is `.task-wrap-up`; `.wiggum-wrap-up` is legacy and still supported.
-If either signal exists, STOP immediately after this checkpoint.
+If the signal exists, STOP immediately after this checkpoint.
 
 If you do work but don't edit STATUS.md, that work is INVISIBLE to the
 orchestrator and you will be re-spawned to do it again.
@@ -262,6 +261,19 @@ Do NOT:
 - Modify docs listed in `task-runner.yaml → protected_docs` without explicit approval
 - Expand task scope — add tech debt instead
 
+## Steering Messages
+
+During orchestrated runs, the supervisor may send steering messages to adjust
+your approach. These messages appear in your conversation as user messages at
+turn boundaries. They are also logged in the STATUS.md execution log as
+`⚠️ Steering` entries for audit visibility.
+
+When you receive a steering message:
+1. **Read it carefully** — it contains course corrections from the supervisor
+2. **Adjust your approach** as directed
+3. **Continue working** — do not stop or restart; incorporate the guidance naturally
+4. Steering messages are authoritative — treat them like direct instructions
+
 ## Error Handling
 
 - If stuck on the same issue after 3 attempts, document the blocker in STATUS.md