taskplane 0.18.1 → 0.20.0

package/dashboard/server.cjs

@@ -1117,6 +1117,59 @@ function serveStatusMd(req, res, taskId) {
   res.end(JSON.stringify({ error: "STATUS.md not found" }));
 }
 
+// ─── Dashboard Preferences ──────────────────────────────────────────────────
+
+function getPreferencesPath() {
+  return path.join(REPO_ROOT, ".pi", "dashboard-preferences.json");
+}
+
+function handleGetPreferences(req, res) {
+  const prefsPath = getPreferencesPath();
+  let prefs = { theme: "dark" };
+  try {
+    if (fs.existsSync(prefsPath)) {
+      prefs = JSON.parse(fs.readFileSync(prefsPath, "utf8"));
+    }
+  } catch { /* use defaults */ }
+  res.writeHead(200, {
+    "Content-Type": "application/json",
+    "Access-Control-Allow-Origin": "*",
+  });
+  res.end(JSON.stringify(prefs));
+}
+
+function handlePostPreferences(req, res) {
+  let body = "";
+  req.on("data", (chunk) => { body += chunk; });
+  req.on("end", () => {
+    try {
+      const incoming = JSON.parse(body);
+      const prefsPath = getPreferencesPath();
+      let existing = {};
+      try {
+        if (fs.existsSync(prefsPath)) {
+          existing = JSON.parse(fs.readFileSync(prefsPath, "utf8"));
+        }
+      } catch { /* start fresh */ }
+      const merged = { ...existing, ...incoming };
+      const dir = path.dirname(prefsPath);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(prefsPath, JSON.stringify(merged, null, 2) + "\n");
+      res.writeHead(200, {
+        "Content-Type": "application/json",
+        "Access-Control-Allow-Origin": "*",
+      });
+      res.end(JSON.stringify(merged));
+    } catch (err) {
+      res.writeHead(400, {
+        "Content-Type": "application/json",
+        "Access-Control-Allow-Origin": "*",
+      });
+      res.end(JSON.stringify({ error: "Invalid JSON" }));
+    }
+  });
+}
+
 // ─── HTTP Server ────────────────────────────────────────────────────────────
 
 function createServer() {
@@ -1146,6 +1199,18 @@ function createServer() {
     } else if (pathname.startsWith("/api/status-md/") && req.method === "GET") {
       const taskId = decodeURIComponent(pathname.slice("/api/status-md/".length));
       serveStatusMd(req, res, taskId);
+    } else if (pathname === "/api/preferences" && req.method === "GET") {
+      handleGetPreferences(req, res);
+    } else if (pathname === "/api/preferences" && req.method === "POST") {
+      handlePostPreferences(req, res);
+    } else if (req.method === "OPTIONS") {
+      // CORS preflight for POST
+      res.writeHead(204, {
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+        "Access-Control-Allow-Headers": "Content-Type",
+      });
+      res.end();
     } else {
       serveStatic(req, res);
     }

package/extensions/task-runner.ts

@@ -1111,8 +1111,78 @@ function generateReviewRequest(
 }
 
 function extractVerdict(reviewContent: string): string {
+	// Primary: standard format "### Verdict: APPROVE|REVISE|RETHINK"
 	const match = reviewContent.match(/###?\s*Verdict[:\s]*(APPROVE|REVISE|RETHINK)/i);
-	return match ? match[1].toUpperCase() : "UNKNOWN";
+	if (match) return match[1].toUpperCase();
+
+	// TP-068: Tolerate non-standard verdict formats from models that don't
+	// follow the exact template (e.g., "Changes requested", "Needs revision").
+	const lower = reviewContent.toLowerCase();
+	if (/\b(changes?\s+requested|needs?\s+revision|please\s+revise|must\s+revise)\b/.test(lower)) {
+		return "REVISE";
+	}
+	if (/\b(looks?\s+good|no\s+issues?\s+found|approved?)\b/.test(lower)) {
+		return "APPROVE";
+	}
+	if (/\b(fundamentally\s+wrong|rethink|reconsider\s+the\s+approach)\b/.test(lower)) {
+		return "RETHINK";
+	}
+
+	return "UNKNOWN";
+}
+
+/**
+ * Process a review verdict: extract the verdict from review content, log it,
+ * update the status file, and build the result text for the worker.
+ *
+ * Shared by the persistent reviewer path and the fallback fresh-spawn path
+ * in the review_step tool handler.
+ */
+function processReviewVerdict(
+	reviewContent: string | null,
+	statusPath: string,
+	num: string,
+	reviewType: string,
+	stepNum: number,
+	reviewCounter: number,
+	suffix?: string,
+): { verdict: string; resultText: string } {
+	let verdict = "UNKNOWN";
+	let reviseDetails = "";
+	if (reviewContent) {
+		verdict = extractVerdict(reviewContent);
+		if (verdict === "REVISE") {
+			const summaryMatch = reviewContent.match(/###?\s*Summary[:\s]*([\s\S]*?)(?=###|$)/i);
+			reviseDetails = summaryMatch
+				? summaryMatch[1].trim().slice(0, 500)
+				: "See review file for details.";
+		}
+	} else {
+		verdict = "UNAVAILABLE";
+		const label = suffix ? `${suffix} reviewer` : "reviewer";
+		logExecution(statusPath, `Reviewer R${num}`,
+			`${reviewType} review — ${label} did not produce output`);
+	}
+
+	const reviewFile = `.reviews/R${num}-${reviewType}-step${stepNum}.md`;
+	logReview(statusPath, `R${num}`, reviewType, stepNum, verdict, reviewFile);
+	const logSuffix = suffix ? ` (${suffix})` : "";
+	logExecution(statusPath, `Review R${num}`,
+		`${reviewType} Step ${stepNum}: ${verdict}${logSuffix}`);
+	updateStatusField(statusPath, "Review Counter", `${reviewCounter}`);
+
+	let resultText: string;
+	if (verdict === "APPROVE") {
+		resultText = "APPROVE";
+	} else if (verdict === "REVISE") {
+		resultText = `REVISE: ${reviseDetails}\n\nFull review: ${reviewFile}`;
+	} else if (verdict === "RETHINK") {
+		resultText = `RETHINK — reconsider your approach. See ${reviewFile}`;
+	} else {
+		resultText = `UNAVAILABLE — reviewer did not produce a usable verdict.`;
+	}
+
+	return { verdict, resultText };
 }
 
 // ── Subagent Spawner ─────────────────────────────────────────────────
@@ -2304,8 +2374,11 @@ export default function (pi: ExtensionAPI) {
 					// Initial prompt tells the reviewer to call wait_for_review
 					const initialPrompt =
 						"You are a persistent reviewer for this task. " +
-						"Call the `wait_for_review` tool now to receive your first review request. " +
-						"After writing each review, call `wait_for_review` again for the next one.";
+						"Use the `wait_for_review` tool now to receive your first review request. " +
+						"IMPORTANT: `wait_for_review` is a REGISTERED EXTENSION TOOL — call it " +
+						"the same way you call `read`, `write`, `edit`, or `grep`. " +
+						"Do NOT run it via `bash` or any shell command. " +
+						"After writing each review, use `wait_for_review` again for the next one.";
 
 					const spawned = spawnAgentTmux({
 						sessionName,
@@ -2375,8 +2448,14 @@ export default function (pi: ExtensionAPI) {
 				/**
 				 * Poll for the verdict file to appear (written by the reviewer).
 				 * Same pattern as the original review_step handler.
+				 *
+				 * Early-exit detection (TP-068): If the reviewer exits within 30s
+				 * of spawn without producing a verdict, it likely failed to use the
+				 * wait_for_review tool correctly (e.g., called it via bash). This
+				 * triggers a faster fallback instead of waiting 30 minutes.
 				 */
-				async function pollForVerdict(): Promise<string> {
+				async function pollForVerdict(spawnTime?: number): Promise<string> {
+					const EARLY_EXIT_THRESHOLD_MS = 30_000; // 30 seconds
 					const verdictTimeout = 30 * 60 * 1000; // 30 minutes
 					const pollStart = Date.now();
 					while (Date.now() - pollStart < verdictTimeout) {
@@ -2385,6 +2464,13 @@ export default function (pi: ExtensionAPI) {
 						}
 						// Also check if persistent reviewer died while we're waiting
 						if (state.persistentReviewerSession && !isPersistentReviewerAlive()) {
+							// TP-068: Detect early exit as tool compatibility failure
+							if (spawnTime && (Date.now() - spawnTime) < EARLY_EXIT_THRESHOLD_MS) {
+								throw new Error(
+									"Persistent reviewer exited within 30s of spawn without producing a verdict — " +
+									"wait_for_review tool may not be supported by this model (e.g., called via bash instead of as a registered tool)"
+								);
+							}
 							throw new Error("Persistent reviewer session died while waiting for verdict");
 						}
 						await new Promise(r => setTimeout(r, 2000));
@@ -2406,7 +2492,10 @@ export default function (pi: ExtensionAPI) {
 						state.persistentReviewerSignalNum = 0;
 					}
 
+					// Track spawn time for early-exit detection (TP-068)
+					let spawnTime: number | undefined;
 					if (needsSpawn) {
+						spawnTime = Date.now();
 						spawnPersistentReviewer();
 						// Give the reviewer a moment to start and call wait_for_review
 						await new Promise(r => setTimeout(r, 5000));
@@ -2415,8 +2504,8 @@ export default function (pi: ExtensionAPI) {
 					// Signal the reviewer with the new request
 					signalPersistentReviewer();
 
-					// Poll for the verdict file
-					const reviewContent = await pollForVerdict();
+					// Poll for the verdict file (pass spawnTime for early-exit detection)
+					const reviewContent = await pollForVerdict(spawnTime);
 
 					// Stop the per-review timer
 					if (state.reviewerTimer) clearInterval(state.reviewerTimer);
@@ -2425,29 +2514,10 @@ export default function (pi: ExtensionAPI) {
 					writeLaneState(state);
 					updateWidgets();
 
-					// Extract verdict from review output
-					let verdict = "UNKNOWN";
-					let reviseDetails = "";
-					if (reviewContent) {
-						verdict = extractVerdict(reviewContent);
-						if (verdict === "REVISE") {
-							const summaryMatch = reviewContent.match(/###?\s*Summary[:\s]*([\s\S]*?)(?=###|$)/i);
-							reviseDetails = summaryMatch
-								? summaryMatch[1].trim().slice(0, 500)
-								: "See review file for details.";
-						}
-					} else {
-						verdict = "UNAVAILABLE";
-						logExecution(statusPath, `Reviewer R${num}`,
-							`${reviewType} review — reviewer did not produce output`);
-					}
-
-					// Log the review in STATUS.md
-					logReview(statusPath, `R${num}`, reviewType, stepNum, verdict,
-						`.reviews/R${num}-${reviewType}-step${stepNum}.md`);
-					logExecution(statusPath, `Review R${num}`,
-						`${reviewType} Step ${stepNum}: ${verdict}`);
-					updateStatusField(statusPath, "Review Counter", `${state.reviewCounter}`);
+					// Extract verdict and build result
+					const { resultText } = processReviewVerdict(
+						reviewContent, statusPath, num, reviewType, stepNum, state.reviewCounter,
+					);
 
 					// Set reviewer to idle (NOT clear — persistent session stays alive)
 					state.reviewerStatus = "idle";
@@ -2458,18 +2528,6 @@ export default function (pi: ExtensionAPI) {
 					writeLaneState(state);
 					updateWidgets();
 
-					// Return verdict to the worker
-					let resultText: string;
-					if (verdict === "APPROVE") {
-						resultText = "APPROVE";
-					} else if (verdict === "REVISE") {
-						resultText = `REVISE: ${reviseDetails}\n\nFull review: .reviews/R${num}-${reviewType}-step${stepNum}.md`;
-					} else if (verdict === "RETHINK") {
-						resultText = `RETHINK — reconsider your approach. See .reviews/R${num}-${reviewType}-step${stepNum}.md`;
-					} else {
-						resultText = `UNAVAILABLE — reviewer did not produce a usable verdict.`;
-					}
-
 					return {
 						content: [{ type: "text" as const, text: resultText }],
 						details: undefined,
@@ -2527,61 +2585,43 @@ export default function (pi: ExtensionAPI) {
 						updateWidgets();
 
 						// Extract verdict from fallback review
-						let verdict = "UNKNOWN";
-						let reviseDetails = "";
-						if (existsSync(outputPath)) {
-							const review = readFileSync(outputPath, "utf-8");
-							verdict = extractVerdict(review);
-							if (verdict === "REVISE") {
-								const summaryMatch = review.match(/###?\s*Summary[:\s]*([\s\S]*?)(?=###|$)/i);
-								reviseDetails = summaryMatch
-									? summaryMatch[1].trim().slice(0, 500)
-									: "See review file for details.";
-							}
-						} else {
-							verdict = "UNAVAILABLE";
-							logExecution(statusPath, `Reviewer R${num}`,
-								`${reviewType} review — fallback reviewer did not produce output`);
-						}
-
-						logReview(statusPath, `R${num}`, reviewType, stepNum, verdict,
-							`.reviews/R${num}-${reviewType}-step${stepNum}.md`);
-						logExecution(statusPath, `Review R${num}`,
-							`${reviewType} Step ${stepNum}: ${verdict} (fallback)`);
-						updateStatusField(statusPath, "Review Counter", `${state.reviewCounter}`);
+						const fallbackContent = existsSync(outputPath)
+							? readFileSync(outputPath, "utf-8")
+							: null;
+						const { resultText } = processReviewVerdict(
+							fallbackContent, statusPath, num, reviewType, stepNum, state.reviewCounter, "fallback",
+						);
 
 						clearReviewerState();
 						writeLaneState(state);
 						updateWidgets();
 
-						let resultText: string;
-						if (verdict === "APPROVE") {
-							resultText = "APPROVE";
-						} else if (verdict === "REVISE") {
-							resultText = `REVISE: ${reviseDetails}\n\nFull review: .reviews/R${num}-${reviewType}-step${stepNum}.md`;
-						} else if (verdict === "RETHINK") {
-							resultText = `RETHINK — reconsider your approach. See .reviews/R${num}-${reviewType}-step${stepNum}.md`;
-						} else {
-							resultText = `UNAVAILABLE — reviewer did not produce a usable verdict.`;
-						}
-
 						return {
 							content: [{ type: "text" as const, text: resultText }],
 							details: undefined,
 						};
 					} catch (fallbackErr: any) {
-						// Both persistent and fallback failed
+						// Both persistent and fallback failed — TP-068: clear logging
 						clearInterval(state.reviewerTimer);
 						clearReviewerState();
 						state.reviewerStatus = "error";
 						writeLaneState(state);
 						updateWidgets();
 
+						const skipMsg = `⚠️ Reviews skipped for Step ${stepNum} — reviewer model could not process ${reviewType} review request. Both persistent and fallback modes failed.`;
+						console.error(`[task-runner] ${skipMsg}`);
 						logExecution(statusPath, `Reviewer R${num}`,
-							`${reviewType} review — both persistent and fallback failed: ${fallbackErr?.message || fallbackErr}`);
+							`${skipMsg} Error: ${fallbackErr?.message || fallbackErr}`);
+
+						// TP-068: Ensure shutdown signal is written even on double failure
+						try {
+							const shutdownPath = join(reviewsDir, REVIEWER_SHUTDOWN_SIGNAL);
+							if (!existsSync(reviewsDir)) mkdirSync(reviewsDir, { recursive: true });
+							writeFileSync(shutdownPath, "shutdown");
+						} catch {}
 
 						return {
-							content: [{ type: "text" as const, text: `UNAVAILABLE — reviewer error: ${fallbackErr?.message || fallbackErr}` }],
+							content: [{ type: "text" as const, text: `UNAVAILABLE — ${skipMsg}` }],
 							details: undefined,
 						};
 					}
@@ -2977,6 +3017,31 @@ export default function (pi: ExtensionAPI) {
 				: `  - Step ${s.number}: ${s.name}  [already complete — skip]`
 		).join("\n");
 
+		// TP-073: Build nudge for subsequent iterations (iter > 0)
+		// When the worker exited without completing all steps, the next iteration
+		// gets an explicit nudge listing completed/remaining steps and a warning
+		// not to exit prematurely again.
+		let iterationNudge = "";
+		if (state.totalIterations > 1 && remainingSteps.length > 0) {
+			const completedSteps = task.steps.filter(s => !remainingSet.has(s.number));
+			const completedList = completedSteps.length > 0
+				? completedSteps.map(s => `Step ${s.number}: ${s.name}`).join(", ")
+				: "(none)";
+			const remainingList = remainingSteps.map(s => `Step ${s.number}: ${s.name}`).join(", ");
+			iterationNudge = [
+				``,
+				`IMPORTANT: You exited on your previous iteration without completing all steps.`,
+				`Do NOT repeat this — you must complete all remaining steps before stopping.`,
+				``,
+				`Completed steps (do not redo): ${completedList}`,
+				`Remaining steps (focus here): ${remainingList}`,
+				``,
+				`Your final action MUST be a tool call (update STATUS.md). Do NOT produce a`,
+				`text-only response — that will terminate your session prematurely.`,
+				``,
+			].join("\n");
+		}
+
 		const prompt = [
 			`Execute all remaining steps for task ${task.taskId}.`,
 			``,
@@ -2987,7 +3052,7 @@ export default function (pi: ExtensionAPI) {
 			``,
 			`This is iteration ${state.totalIterations}.`,
 			`Read STATUS.md FIRST to find where you left off.`,
-			``,
+			iterationNudge,
 			`Steps:`,
 			stepListing,
 			``,

package/extensions/taskplane/engine-worker.ts

@@ -0,0 +1,289 @@
+/**
+ * Engine Worker Thread Entry Point (TP-071)
+ *
+ * This module serves two purposes:
+ * 1. Exports types and helpers used by extension.ts (main thread)
+ * 2. When executed as a worker_threads Worker, runs the engine in a separate V8 isolate
+ *
+ * Communication:
+ * - Worker → Main: postMessage for notify, monitor-update, engine-event, state-sync, complete, error
+ * - Main → Worker: postMessage for pause/resume/abort control
+ *
+ * @module orch/engine-worker
+ */
+import { parentPort, workerData, isMainThread } from "worker_threads";
+
+import type {
+	EngineEvent,
+	MonitorState,
+	OrchBatchPhase,
+	OrchBatchRuntimeState,
+	OrchestratorConfig,
+	TaskRunnerConfig,
+	WorkspaceConfig,
+	WorkspaceRepoConfig,
+} from "./types.ts";
+
+// ── Types for worker <-> main thread messages ────────────────────────
+
+/**
+ * Messages sent FROM the worker TO the main thread.
+ */
+export type WorkerToMainMessage =
+	| { type: "notify"; msg: string; level: "info" | "warning" | "error" }
+	| { type: "monitor-update"; state: MonitorState }
+	| { type: "engine-event"; event: EngineEvent }
+	| { type: "state-sync"; state: SerializedBatchState }
+	| { type: "complete"; state: SerializedBatchState }
+	| { type: "error"; message: string };
+
+/**
+ * Messages sent FROM the main thread TO the worker.
+ */
+export type WorkerInMessage =
+	| { type: "pause" }
+	| { type: "resume" }
+	| { type: "abort" };
+
+/**
+ * Serializable form of OrchBatchRuntimeState fields synced to main thread.
+ * Only includes fields the main thread needs for display/state tracking.
+ */
+export interface SerializedBatchState {
+	phase: OrchBatchPhase;
+	batchId: string;
+	baseBranch: string;
+	orchBranch: string;
+	mode: string;
+	currentWaveIndex: number;
+	totalWaves: number;
+	totalTasks: number;
+	succeededTasks: number;
+	failedTasks: number;
+	skippedTasks: number;
+	blockedTasks: number;
+	startedAt: number;
+	endedAt: number | null;
+	errors: string[];
+}
+
+/**
+ * Serializable form of WorkspaceConfig (Map → array of entries).
+ */
+export interface SerializedWorkspaceConfig {
+	mode: string;
+	repos: Array<[string, WorkspaceRepoConfig]>;
+	routing: WorkspaceConfig["routing"];
+	configPath: string;
+}
+
+/**
+ * workerData shape passed from the main thread.
+ */
+export interface EngineWorkerData {
+	/** Sentinel flag — distinguishes engine worker from vitest threads */
+	engineWorker: true;
+	/** "execute" for new batch, "resume" for resume */
+	mode: "execute" | "resume";
+	/** User arguments (target string) — only for "execute" mode */
+	args?: string;
+	/** Orchestrator configuration */
+	orchConfig: OrchestratorConfig;
+	/** Task runner configuration */
+	runnerConfig: TaskRunnerConfig;
+	/** Repository root (cwd) */
+	cwd: string;
+	/** Workspace configuration (serialized) — null for repo mode */
+	workspaceConfig?: SerializedWorkspaceConfig | null;
+	/** Workspace root directory */
+	workspaceRoot?: string;
+	/** Agent root directory */
+	agentRoot?: string;
+	/** Force flag for resume */
+	force?: boolean;
+}
+
+// ── Serialization helpers (used by both main thread and worker) ──────
+
+/**
+ * Serialize WorkspaceConfig for cross-thread transfer.
+ * Converts the Map to an array of entries.
+ */
+export function serializeWorkspaceConfig(
+	config: WorkspaceConfig | null | undefined,
+): SerializedWorkspaceConfig | null {
+	if (!config) return null;
+	return {
+		mode: config.mode,
+		repos: [...config.repos.entries()],
+		routing: config.routing,
+		configPath: config.configPath,
+	};
+}
+
+/**
+ * Reconstruct WorkspaceConfig from serialized form.
+ */
+export function deserializeWorkspaceConfig(
+	serialized: SerializedWorkspaceConfig | null | undefined,
+): WorkspaceConfig | null {
+	if (!serialized) return null;
+	return {
+		mode: serialized.mode as WorkspaceConfig["mode"],
+		repos: new Map(serialized.repos),
+		routing: serialized.routing,
+		configPath: serialized.configPath,
+	};
+}
+
+/**
+ * Extract serializable batch state for sync back to main thread.
+ */
+function serializeBatchState(state: OrchBatchRuntimeState): SerializedBatchState {
+	return {
+		phase: state.phase,
+		batchId: state.batchId,
+		baseBranch: state.baseBranch,
+		orchBranch: state.orchBranch,
+		mode: state.mode,
+		currentWaveIndex: state.currentWaveIndex,
+		totalWaves: state.totalWaves,
+		totalTasks: state.totalTasks,
+		succeededTasks: state.succeededTasks,
+		failedTasks: state.failedTasks,
+		skippedTasks: state.skippedTasks,
+		blockedTasks: state.blockedTasks,
+		startedAt: state.startedAt,
+		endedAt: state.endedAt,
+		errors: [...state.errors],
+	};
+}
+
+/**
+ * Apply serialized batch state from worker to main-thread batch state.
+ *
+ * Updates only the fields that the worker thread tracks — preserves
+ * main-thread-only fields like pauseSignal, dependencyGraph, etc.
+ */
+export function applySerializedState(
+	batchState: OrchBatchRuntimeState,
+	serialized: SerializedBatchState,
+): void {
+	batchState.phase = serialized.phase;
+	batchState.batchId = serialized.batchId;
+	batchState.baseBranch = serialized.baseBranch;
+	batchState.orchBranch = serialized.orchBranch;
+	batchState.mode = serialized.mode as OrchBatchRuntimeState["mode"];
+	batchState.currentWaveIndex = serialized.currentWaveIndex;
+	batchState.totalWaves = serialized.totalWaves;
+	batchState.totalTasks = serialized.totalTasks;
+	batchState.succeededTasks = serialized.succeededTasks;
+	batchState.failedTasks = serialized.failedTasks;
+	batchState.skippedTasks = serialized.skippedTasks;
+	batchState.blockedTasks = serialized.blockedTasks;
+	batchState.startedAt = serialized.startedAt;
+	batchState.endedAt = serialized.endedAt;
+	batchState.errors = [...serialized.errors];
+}
+
+// ── Worker main (only runs when loaded as a worker thread) ───────────
+
+// Guard: only run worker main when launched as an engine worker (not vitest threads).
+// In vitest --pool=threads, isMainThread=false and parentPort exists, but
+// workerData won't have the engine-specific shape.
+if (!isMainThread && parentPort && workerData?.engineWorker === true) {
+	// Dynamic imports — only loaded in worker context to avoid circular
+	// dependencies when this module is imported from extension.ts
+	const { executeOrchBatch } = await import("./engine.ts");
+	const { resumeOrchBatch } = await import("./resume.ts");
+	const { freshOrchBatchState } = await import("./types.ts");
+
+	const data = workerData as EngineWorkerData;
+	const port = parentPort;
+
+	// Create a fresh batch state for this worker
+	const batchState: OrchBatchRuntimeState = freshOrchBatchState();
+	batchState.phase = "launching";
+	batchState.startedAt = Date.now();
+
+	// Deserialize workspace config
+	const wsConfig = deserializeWorkspaceConfig(data.workspaceConfig);
+
+	// ── Control signal listener ──────────────────────────────────
+	// Main thread sends pause/resume/abort signals via postMessage.
+	// We apply them to the in-worker batchState.pauseSignal.
+	port.on("message", (msg: WorkerInMessage) => {
+		switch (msg.type) {
+			case "pause":
+				batchState.pauseSignal.paused = true;
+				break;
+			case "resume":
+				batchState.pauseSignal.paused = false;
+				break;
+			case "abort":
+				batchState.pauseSignal.paused = true;
+				break;
+		}
+	});
+
+	// ── Callback factories (replace ctx-dependent callbacks) ─────
+	const onNotify = (message: string, level: "info" | "warning" | "error") => {
+		port.postMessage({ type: "notify", msg: message, level } satisfies WorkerToMainMessage);
+		// Sync batch state on every notify (lightweight — just the summary fields)
+		port.postMessage({ type: "state-sync", state: serializeBatchState(batchState) } satisfies WorkerToMainMessage);
+	};
+
+	const onMonitorUpdate = (state: MonitorState) => {
+		port.postMessage({ type: "monitor-update", state } satisfies WorkerToMainMessage);
+	};
+
+	const onEngineEvent = (event: EngineEvent) => {
+		port.postMessage({ type: "engine-event", event } satisfies WorkerToMainMessage);
+	};
+
+	// ── Execute engine ───────────────────────────────────────────
+	const enginePromise = data.mode === "resume"
+		? resumeOrchBatch(
+			data.orchConfig,
+			data.runnerConfig,
+			data.cwd,
+			batchState,
+			onNotify,
+			onMonitorUpdate,
+			wsConfig,
+			data.workspaceRoot,
+			data.agentRoot,
+			data.force ?? false,
+		)
+		: executeOrchBatch(
+			data.args ?? "",
+			data.orchConfig,
+			data.runnerConfig,
+			data.cwd,
+			batchState,
+			onNotify,
+			onMonitorUpdate,
+			wsConfig,
+			data.workspaceRoot,
+			data.agentRoot,
+			onEngineEvent,
+		);
+
+	enginePromise
+		.then(() => {
+			// Final state sync + completion signal
+			const finalState = serializeBatchState(batchState);
+			port.postMessage({ type: "complete", state: finalState } satisfies WorkerToMainMessage);
+		})
+		.catch((err: unknown) => {
+			const errMsg = err instanceof Error ? err.message : String(err);
+			// Ensure batch state reflects the failure
+			if (batchState.phase !== "completed" && batchState.phase !== "failed") {
+				batchState.phase = "failed";
+				batchState.endedAt = Date.now();
+				batchState.errors.push(`Unhandled engine error: ${errMsg}`);
+			}
+			port.postMessage({ type: "state-sync", state: serializeBatchState(batchState) } satisfies WorkerToMainMessage);
+			port.postMessage({ type: "error", message: errMsg } satisfies WorkerToMainMessage);
+		});
+}