taskplane 0.20.2 → 0.20.3

package/extensions/taskplane/engine-worker.ts

@@ -1,18 +1,20 @@
 /**
- * Engine Worker Thread Entry Point (TP-071)
+ * Engine Child Process 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
+ * 2. When forked as a child process, runs the engine in a separate Node.js process
+ *
+ * Uses child_process.fork() instead of worker_threads because Node v25's
+ * default --experimental-strip-types rejects .ts files inside node_modules.
+ * Fork creates a new process where --experimental-transform-types takes effect.
  *
  * Communication:
- * - Worker → Main: postMessage for notify, monitor-update, engine-event, state-sync, complete, error
- * - Main → Worker: postMessage for pause/resume/abort control
+ * - Child → Parent: process.send() for notify, monitor-update, engine-event, state-sync, complete, error
+ * - Parent → Child: child.send() for init, pause, resume, abort
  *
  * @module orch/engine-worker
  */
-import { parentPort, workerData, isMainThread } from "worker_threads";
-
 import type {
 	EngineEvent,
 	MonitorState,
@@ -186,104 +188,111 @@ export function applySerializedState(
 	batchState.errors = [...serialized.errors];
 }
 
-// ── Worker main (only runs when loaded as a worker thread) ───────────
+// ── Engine main (runs when launched as a forked child process) ───────
 
-// 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");
+// Guard: only run engine main when launched via fork() with the sentinel env var.
+if (process.env.TASKPLANE_ENGINE_FORK === "1" && typeof process.send === "function") {
+	const send = (msg: WorkerToMainMessage) => process.send!(msg);
 
-	const data = workerData as EngineWorkerData;
-	const port = parentPort;
+	// Wait for the init message carrying workerData, then start the engine.
+	process.once("message", async (initMsg: { type: string; data: EngineWorkerData }) => {
+		if (initMsg?.type !== "init") return;
 
-	// Create a fresh batch state for this worker
-	const batchState: OrchBatchRuntimeState = freshOrchBatchState();
-	batchState.phase = "launching";
-	batchState.startedAt = Date.now();
+		// Dynamic imports — only loaded in engine 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");
 
-	// Deserialize workspace config
-	const wsConfig = deserializeWorkspaceConfig(data.workspaceConfig);
+		const data = initMsg.data;
 
-	// ── 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;
-		}
-	});
+		// Create a fresh batch state for this process
+		const batchState: OrchBatchRuntimeState = freshOrchBatchState();
+		batchState.phase = "launching";
+		batchState.startedAt = Date.now();
 
-	// ── 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);
-	};
+		// Deserialize workspace config
+		const wsConfig = deserializeWorkspaceConfig(data.workspaceConfig);
 
-	const onMonitorUpdate = (state: MonitorState) => {
-		port.postMessage({ type: "monitor-update", state } satisfies WorkerToMainMessage);
-	};
+		// ── Control signal listener ──────────────────────────────────
+		// Main process sends pause/resume/abort signals via IPC.
+		// We apply them to the in-process batchState.pauseSignal.
+		process.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;
+			}
+		});
 
-	const onEngineEvent = (event: EngineEvent) => {
-		port.postMessage({ type: "engine-event", event } satisfies WorkerToMainMessage);
-	};
+		// ── Callback factories (replace ctx-dependent callbacks) ─────
+		const onNotify = (message: string, level: "info" | "warning" | "error") => {
+			send({ type: "notify", msg: message, level });
+			// Sync batch state on every notify (lightweight — just the summary fields)
+			send({ type: "state-sync", state: serializeBatchState(batchState) });
+		};
 
-	// ── 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,
-		);
+		const onMonitorUpdate = (state: MonitorState) => {
+			send({ type: "monitor-update", state });
+		};
 
-	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);
-		});
+		const onEngineEvent = (event: EngineEvent) => {
+			send({ type: "engine-event", event });
+		};
+
+		// ── 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);
+				send({ type: "complete", state: finalState });
+				// Disconnect IPC so the child process can exit cleanly
+				process.disconnect?.();
+			})
+			.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}`);
+				}
+				send({ type: "state-sync", state: serializeBatchState(batchState) });
+				send({ type: "error", message: errMsg });
+				process.disconnect?.();
+			});
+	});
 }

package/extensions/taskplane/extension.ts

@@ -5,7 +5,7 @@ import { execSync, execFileSync } from "child_process";
 import { writeFileSync, unlinkSync, mkdirSync, existsSync, readdirSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
-import { Worker } from "worker_threads";
+import { fork, type ChildProcess } from "child_process";
 
 // Direct imports — avoid barrel (index.ts) to prevent loading the entire module graph.
 // Each import targets the specific module where the symbol is defined.
@@ -897,7 +897,7 @@ function resolveEngineWorkerPath(): string {
 	} catch {
 		thisDir = __dirname;
 	}
-	return join(thisDir, "engine-worker-entry.mjs");
+	return join(thisDir, "engine-worker.ts");
 }
 
 /**
@@ -935,19 +935,20 @@ export function startBatchInWorker(
 	updateWidget: () => void,
 	onMonitorUpdate?: (state: import("./types.ts").MonitorState) => void,
 	onTerminal?: () => void,
-): Worker | null {
+): ChildProcess | null {
 	const workerPath = resolveEngineWorkerPath();
 
-	let worker: Worker;
+	let child: ChildProcess;
 	try {
-		worker = new Worker(workerPath, {
-			workerData: wkData,
+		child = fork(workerPath, [], {
 			execArgv: ["--experimental-transform-types", "--no-warnings"],
+			env: { ...process.env, TASKPLANE_ENGINE_FORK: "1" },
+			serialization: "advanced",
 		});
 	} catch (spawnErr: unknown) {
 		const errMsg = spawnErr instanceof Error ? spawnErr.message : String(spawnErr);
 		ctx.ui.notify(
-			`⚠️ Worker thread spawn failed: ${errMsg}\n   Falling back to main-thread execution.`,
+			`⚠️ Engine process spawn failed: ${errMsg}\n   Falling back to main-thread execution.`,
 			"warning",
 		);
 		// Construct fallback engine function from workerData and run on main thread
@@ -983,8 +984,11 @@ export function startBatchInWorker(
 		return null;
 	}
 
+	// Send workerData as first IPC message (fork doesn't have workerData)
+	child.send({ type: "init", data: wkData });
+
 	// Terminal settlement guard (R001 §3): ensures onTerminal fires at most once.
-	// The worker can emit error + complete messages, followed by exit event.
+	// The child can emit error + complete messages, followed by exit event.
 	// Without this guard, summary/integration/supervisor flows would fire multiple times.
 	let settled = false;
 	const settle = () => {
@@ -993,7 +997,7 @@ export function startBatchInWorker(
 		onTerminal?.();
 	};
 
-	worker.on("message", (msg: WorkerToMainMessage) => {
+	child.on("message", (msg: WorkerToMainMessage) => {
 		switch (msg.type) {
 			case "notify":
 				ctx.ui.notify(msg.msg, msg.level);
@@ -1005,7 +1009,7 @@ export function startBatchInWorker(
 				break;
 
 			case "engine-event":
-				// Engine events are already persisted to events.jsonl by the worker.
+				// Engine events are already persisted to events.jsonl by the child.
 				// No additional handling needed on the main thread.
 				break;
 
@@ -1036,15 +1040,15 @@ export function startBatchInWorker(
 		}
 	});
 
-	worker.on("error", (err: Error) => {
-		// Worker threw an uncaught exception
+	child.on("error", (err: Error) => {
+		// Child process encountered an error
 		if (batchState.phase !== "completed" && batchState.phase !== "failed") {
 			batchState.phase = "failed";
 			batchState.endedAt = Date.now();
-			batchState.errors.push(`Worker thread error: ${err.message}`);
+			batchState.errors.push(`Engine process error: ${err.message}`);
 		}
 		ctx.ui.notify(
-			`❌ Engine worker thread error: ${err.message}\n` +
+			`❌ Engine process error: ${err.message}\n` +
 			`   Batch ${batchState.batchId} marked as failed.`,
 			"error",
 		);
@@ -1052,16 +1056,16 @@ export function startBatchInWorker(
 		settle();
 	});
 
-	worker.on("exit", (code: number) => {
+	child.on("exit", (code: number | null) => {
 		if (code !== 0 && !settled) {
 			// Non-zero exit that wasn't handled by 'error' or 'complete'
 			if (batchState.phase !== "completed" && batchState.phase !== "failed") {
 				batchState.phase = "failed";
 				batchState.endedAt = Date.now();
-				batchState.errors.push(`Worker thread exited with code ${code}`);
+				batchState.errors.push(`Engine process exited with code ${code}`);
 			}
 			ctx.ui.notify(
-				`❌ Engine worker thread exited unexpectedly (code ${code}).`,
+				`❌ Engine process exited unexpectedly (code ${code}).`,
 				"error",
 			);
 			updateWidget();
@@ -1387,9 +1391,9 @@ export default function (pi: ExtensionAPI) {
 	let orchWidgetCtx: ExtensionContext | undefined;
 	let latestMonitorState: MonitorState | null = null;
 
-	// ── TP-071: Active engine worker thread ──────────────────────────
-	// Tracked so pause/abort can post control messages to the worker.
-	let activeWorker: Worker | null = null;
+	// ── TP-071: Active engine child process ──────────────────────────
+	// Tracked so pause/abort can send control messages to the engine.
+	let activeWorker: ChildProcess | null = null;
 
 	// ── Supervisor State (TP-041) ────────────────────────────────────
 	let supervisorState = freshSupervisorState();
@@ -2006,8 +2010,8 @@ export default function (pi: ExtensionAPI) {
 			return ORCH_MESSAGES.pauseAlreadyPaused(orchBatchState.batchId);
 		}
 		orchBatchState.pauseSignal.paused = true;
-		// TP-071: Forward pause to worker thread (its pauseSignal is separate)
-		activeWorker?.postMessage({ type: "pause" });
+		// TP-071: Forward pause to engine process (its pauseSignal is separate)
+		activeWorker?.send({ type: "pause" });
 		updateOrchWidget();
 		return ORCH_MESSAGES.pauseActivated(orchBatchState.batchId);
 	}
@@ -2197,15 +2201,15 @@ export default function (pi: ExtensionAPI) {
 			orchBatchState.pauseSignal.paused = true;
 			messages.push("  ✓ Pause signal set on in-memory batch state");
 		}
-		// TP-071: Forward pause to worker and terminate on hard abort
+		// TP-071: Forward pause to engine and kill on hard abort
 		if (activeWorker) {
-			activeWorker.postMessage({ type: "pause" });
+			activeWorker.send({ type: "pause" });
 			if (hard) {
-				activeWorker.terminate();
+				activeWorker.kill();
 				activeWorker = null;
-				messages.push("  ✓ Engine worker thread terminated (hard abort)");
+				messages.push("  ✓ Engine process killed (hard abort)");
 			} else {
-				messages.push("  ✓ Pause signal forwarded to engine worker thread");
+				messages.push("  ✓ Pause signal forwarded to engine process");
 			}
 		}
 
@@ -3283,13 +3287,13 @@ export default function (pi: ExtensionAPI) {
 	// Ensure supervisor lockfile/heartbeat are cleaned up on normal session exit.
 	// This avoids leaving a live-looking lock when the process exits cleanly.
 	pi.on("session_end", async () => {
-		// TP-071: Terminate engine worker thread on session exit
+		// TP-071: Kill engine process on session exit
 		if (activeWorker) {
 			try {
-				activeWorker.terminate();
+				activeWorker.kill();
 				activeWorker = null;
 			} catch {
-				// Best effort — worker may already be dead
+				// Best effort — process may already be dead
 			}
 		}
 		try {

package/package.json

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

package/extensions/taskplane/engine-worker-entry.mjs

@@ -1,10 +0,0 @@
-/**
- * Thin entry point for the engine worker thread.
- *
- * Node's Worker constructor rejects .ts files inside node_modules when
- * --experimental-strip-types is active (the default in Node v25+).
- * This .mjs wrapper avoids the restriction — Node loads .mjs files
- * without TypeScript processing, then --experimental-transform-types
- * (passed via execArgv) handles subsequent .ts imports.
- */
-import "./engine-worker.ts";