taskplane 0.20.5 → 0.21.0

package/bin/rpc-wrapper.mjs

@@ -331,6 +331,8 @@ function createSessionState() {
 		currentTool: null,
 		error: null,
 		agentEnded: false,
+		/** Authoritative context usage from pi get_session_stats (null if unavailable) */
+		contextUsage: null,
 	};
 }
 
@@ -414,6 +416,10 @@ function applyEvent(state, event) {
 			if (event.success === false && event.error) {
 				state.error = event.error;
 			}
+			// get_session_stats response — extract authoritative contextUsage
+			if (event.success === true && event.data?.contextUsage) {
+				state.contextUsage = event.data.contextUsage;
+			}
 			break;
 		}
 
@@ -455,6 +461,8 @@ function buildExitSummary(state, exitCode, exitSignal, errorOverride, startTime)
 		durationSec,
 		lastToolCall: state.lastToolCall,
 		error: finalError,
+		// Authoritative context usage from pi ≥ 0.63.0 (null if unavailable)
+		contextUsage: state.contextUsage || null,
 	};
 
 	return redactSummary(rawSummary);
@@ -614,6 +622,22 @@ function closeStdin() {
 	}
 }
 
+/**
+ * Query pi for authoritative session stats including contextUsage.
+ * Available in pi ≥ 0.63.0 (RPC get_session_stats exposes contextUsage).
+ * Safe to call on older versions — the command is ignored or returns
+ * without the field, and state.contextUsage stays null.
+ */
+function querySessionStats() {
+	try {
+		if (proc.stdin && !proc.stdin.destroyed) {
+			proc.stdin.write(JSON.stringify({ type: "get_session_stats" }) + "\n");
+		}
+	} catch {
+		// stdin may be closed — ignore
+	}
+}
+
 // ── Route RPC events ─────────────────────────────────────────────────
 
 function handleEvent(event) {
@@ -628,6 +652,13 @@ function handleEvent(event) {
 	// Side effects that depend on the event type (IO, stdin lifecycle, display)
 	switch (event.type) {
 		case "message_end":
+			displayProgress(state);
+			// Query pi for authoritative context usage (pi ≥ 0.63.0).
+			// Falls back gracefully: older pi versions ignore the command
+			// or return a response without contextUsage — state.contextUsage stays null.
+			querySessionStats();
+			break;
+
 		case "tool_execution_start":
 			displayProgress(state);
 			break;

package/bin/taskplane.mjs

@@ -1193,6 +1193,15 @@ async function cmdInit(args) {
 			{ skipIfExists: !force, label: ".pi/taskplane-workspace.yaml" },
 		);
 
+		// ── Gitignore enforcement in config repo (Scenario D) ───
+		// Ensure .gitignore exists even when reusing existing config
+		const gitignoreResult = ensureGitignoreEntries(configRepoRoot, { dryRun: false, prefix: ".taskplane/" });
+		if (gitignoreResult.created) {
+			console.log(`  ${c.green}create${c.reset} ${configRepo}/.gitignore`);
+		} else if (gitignoreResult.added.length > 0) {
+			console.log(`  ${c.green}update${c.reset} ${configRepo}/.gitignore (${gitignoreResult.added.length} entries added)`);
+		}
+
 		console.log(`\n${OK} ${c.bold}Workspace pointer created.${c.reset}\n`);
 		console.log(`  Config:  ${c.cyan}${configRepo}/.taskplane/${c.reset}`);
 		console.log(`  Pointer: ${c.cyan}.pi/taskplane-pointer.json${c.reset}`);
@@ -2510,18 +2519,20 @@ function cmdDoctor() {
 	console.log();
 	const hasUnifiedJson = fs.existsSync(path.join(configLocation.root, configLocation.prefix, "taskplane-config.json"));
 	const configFiles = [
-		{ path: "taskplane-config.json", required: false },
-		{ path: "task-runner.yaml", required: !hasUnifiedJson },
-		{ path: "task-orchestrator.yaml", required: !hasUnifiedJson },
-		{ path: "agents/task-worker.md", required: true },
-		{ path: "agents/task-reviewer.md", required: true },
-		{ path: "agents/task-merger.md", required: true },
-		{ path: "agents/supervisor.md", required: false },
-		{ path: "taskplane.json", required: false },
+		{ path: "taskplane-config.json", required: false, hide: false },
+		// YAML configs are legacy fallback — hide when taskplane-config.json exists
+		{ path: "task-runner.yaml", required: !hasUnifiedJson, hide: hasUnifiedJson },
+		{ path: "task-orchestrator.yaml", required: !hasUnifiedJson, hide: hasUnifiedJson },
+		{ path: "agents/task-worker.md", required: true, hide: false },
+		{ path: "agents/task-reviewer.md", required: true, hide: false },
+		{ path: "agents/task-merger.md", required: true, hide: false },
+		// supervisor.md is created by /orch; taskplane.json is created at runtime
+		{ path: "agents/supervisor.md", required: false, hide: true },
+		{ path: "taskplane.json", required: false, hide: true },
 	];
 
 	let missingRequiredConfigs = 0;
-	for (const { path: relPath, required } of configFiles) {
+	for (const { path: relPath, required, hide } of configFiles) {
 		const fullPath = path.join(configLocation.root, configLocation.prefix, relPath);
 		const displayPath = `${configLocation.label}/${relPath}`;
 		const exists = fs.existsSync(fullPath);
@@ -2531,7 +2542,8 @@ function cmdDoctor() {
 			console.log(`  ${FAIL} ${displayPath} missing`);
 			missingRequiredConfigs++;
 			issues++;
-		} else {
+		} else if (!hide) {
+			// Show optional files only when they're relevant (not superseded)
 			console.log(`  ${WARN} ${displayPath} missing ${c.dim}(optional)${c.reset}`);
 		}
 	}

package/extensions/task-runner.ts

@@ -1367,6 +1367,8 @@ interface SidecarTelemetryDelta {
 	lastRetryError: string;
 	/** 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;
 }
 
 /**
@@ -1385,7 +1387,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,
+		hadEvents: false, contextUsage: null,
 	};
 
 	// Gracefully handle missing file (wrapper hasn't written yet)
@@ -1496,6 +1498,21 @@ function tailSidecarJsonl(filePath: string, tailState: SidecarTailState): Sideca
 				tailState.retryActive = false;
 				break;
 			}
+
+			case "response": {
+				// 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") {
+						delta.contextUsage = {
+							percentUsed: cu.percentUsed,
+							totalTokens: cu.totalTokens || 0,
+							maxTokens: cu.maxTokens || 0,
+						};
+					}
+				}
+				break;
+			}
 		}
 	}
 
@@ -2405,8 +2422,10 @@ export default function (pi: ExtensionAPI) {
 								state.reviewerLastTool = delta.lastTool;
 							}
 
-							// Context %
-							if (delta.latestTotalTokens > 0 && contextWindow > 0) {
+							// Context % — prefer authoritative contextUsage (pi ≥ 0.63.0)
+							if (delta.contextUsage) {
+								state.reviewerContextPct = delta.contextUsage.percentUsed;
+							} else if (delta.latestTotalTokens > 0 && contextWindow > 0) {
 								state.reviewerContextPct = (delta.latestTotalTokens / contextWindow) * 100;
 							}
 
@@ -2566,7 +2585,10 @@ export default function (pi: ExtensionAPI) {
 								state.reviewerCostUsd += delta.cost;
 								state.reviewerToolCount += delta.toolCalls;
 								if (delta.lastTool) state.reviewerLastTool = delta.lastTool;
-								if (delta.latestTotalTokens > 0 && contextWindow > 0) {
+								// Context % — prefer authoritative contextUsage (pi ≥ 0.63.0)
+								if (delta.contextUsage) {
+									state.reviewerContextPct = delta.contextUsage.percentUsed;
+								} else if (delta.latestTotalTokens > 0 && contextWindow > 0) {
 									state.reviewerContextPct = (delta.latestTotalTokens / contextWindow) * 100;
 								}
 								writeLaneState(state);
@@ -3140,18 +3162,24 @@ export default function (pi: ExtensionAPI) {
 						state.workerLastRetryError = delta.lastRetryError;
 					}
 
-					// Context % (same as subprocess onContextPct)
-					// totalTokens is cumulative from the most recent message_end
-					if (delta.latestTotalTokens > 0 && contextWindow > 0) {
-						const pct = (delta.latestTotalTokens / contextWindow) * 100;
-						state.workerContextPct = pct;
-						if (pct >= warnPct) {
-							writeWrapUpSignal(`Wrap up (context ${Math.round(pct)}%)`);
-						}
-						if (pct >= killPct && state.workerStatus === "running") {
-							console.error(`[task-runner] tmux worker: context limit (${Math.round(pct)}%) — killing session '${sessionName}'`);
-							killReason = "context";
-							spawned.kill();
+					// 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;
+						if (pct > 0) {
+							state.workerContextPct = pct;
+							if (pct >= warnPct) {
+								writeWrapUpSignal(`Wrap up (context ${Math.round(pct)}%)`);
+							}
+							if (pct >= killPct && state.workerStatus === "running") {
+								console.error(`[task-runner] tmux worker: context limit (${Math.round(pct)}%) — killing session '${sessionName}'`);
+								killReason = "context";
+								spawned.kill();
+							}
 						}
 					}
 

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

@@ -0,0 +1,18 @@
+/**
+ * Fork entry point for the engine child process.
+ *
+ * Node v25 blocks .ts files inside node_modules regardless of flags.
+ * This .mjs file loads cleanly (no TypeScript processing needed), then
+ * uses jiti to import engine-worker.ts — bypassing Node's restriction.
+ *
+ * jiti is the same TypeScript runtime loader that Pi uses to load
+ * extensions. It transforms .ts files itself, independent of Node's
+ * --experimental-strip-types support.
+ */
+import { createJiti } from "jiti";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const jiti = createJiti(import.meta.url);
+await jiti.import(join(__dirname, "engine-worker.ts"));

package/extensions/taskplane/extension.ts

@@ -5,8 +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";
-// child_process.fork() disabled — Node v25 blocks .ts in node_modules.
-// Re-enable when engine-worker ships as pre-compiled .js bundle.
+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.
@@ -898,7 +897,7 @@ function resolveEngineWorkerPath(): string {
 	} catch {
 		thisDir = __dirname;
 	}
-	return join(thisDir, "engine-worker.ts");
+	return join(thisDir, "engine-worker-entry.mjs");
 }
 
 /**
@@ -936,14 +935,24 @@ export function startBatchInWorker(
 	updateWidget: () => void,
 	onMonitorUpdate?: (state: import("./types.ts").MonitorState) => void,
 	onTerminal?: () => void,
-): null {
-	// ── Main-thread execution (TP-071 fork disabled) ─────────────
-	// Node v25 blocks .ts files inside node_modules regardless of
-	// --experimental-strip-types or --experimental-transform-types.
-	// Until we ship a pre-compiled engine bundle, the engine runs on
-	// the main thread via startBatchAsync(). The supervisor stays
-	// responsive because engine work is async I/O (tmux, git, fs).
-	{
+): ChildProcess | null {
+	const workerPath = resolveEngineWorkerPath();
+
+	let child: ChildProcess;
+	try {
+		// Fork a child process to run the engine in a separate isolate.
+		// The entry point is a .mjs file that uses jiti to load .ts files,
+		// bypassing Node v25's restriction on .ts in node_modules.
+		child = fork(workerPath, [], {
+			env: { ...process.env, TASKPLANE_ENGINE_FORK: "1" },
+			serialization: "advanced",
+		});
+	} catch (spawnErr: unknown) {
+		const errMsg = spawnErr instanceof Error ? spawnErr.message : String(spawnErr);
+		ctx.ui.notify(
+			`⚠️ Engine process spawn failed: ${errMsg}\n   Falling back to main-thread execution.`,
+			"warning",
+		);
 		// Construct fallback engine function from workerData and run on main thread
 		const wsConfig = wkData.workspaceConfig
 			? deserializeWorkspaceConfig(wkData.workspaceConfig)
@@ -976,6 +985,91 @@ export function startBatchInWorker(
 		startBatchAsync(fallbackFn, batchState, ctx, updateWidget, onTerminal);
 		return null;
 	}
+
+	// Send workerData as first IPC message
+	child.send({ type: "init", data: wkData });
+
+	// Terminal settlement guard (R001 §3): ensures onTerminal fires at most once.
+	let settled = false;
+	const settle = () => {
+		if (settled) return;
+		settled = true;
+		onTerminal?.();
+	};
+
+	child.on("message", (msg: WorkerToMainMessage) => {
+		switch (msg.type) {
+			case "notify":
+				ctx.ui.notify(msg.msg, msg.level);
+				updateWidget();
+				break;
+
+			case "monitor-update":
+				onMonitorUpdate?.(msg.state);
+				break;
+
+			case "engine-event":
+				break;
+
+			case "state-sync":
+				applySerializedState(batchState, msg.state);
+				updateWidget();
+				break;
+
+			case "complete":
+				applySerializedState(batchState, msg.state);
+				updateWidget();
+				settle();
+				break;
+
+			case "error":
+				if (batchState.phase !== "completed" && batchState.phase !== "failed") {
+					batchState.phase = "failed";
+					batchState.endedAt = Date.now();
+					batchState.errors.push(`Unhandled engine error: ${msg.message}`);
+				}
+				ctx.ui.notify(
+					`❌ Engine crashed with unhandled error: ${msg.message}\n` +
+					`   Batch ${batchState.batchId} marked as failed.`,
+					"error",
+				);
+				updateWidget();
+				break;
+		}
+	});
+
+	child.on("error", (err: Error) => {
+		if (batchState.phase !== "completed" && batchState.phase !== "failed") {
+			batchState.phase = "failed";
+			batchState.endedAt = Date.now();
+			batchState.errors.push(`Engine process error: ${err.message}`);
+		}
+		ctx.ui.notify(
+			`❌ Engine process error: ${err.message}\n` +
+			`   Batch ${batchState.batchId} marked as failed.`,
+			"error",
+		);
+		updateWidget();
+		settle();
+	});
+
+	child.on("exit", (code: number | null) => {
+		if (code !== 0 && !settled) {
+			if (batchState.phase !== "completed" && batchState.phase !== "failed") {
+				batchState.phase = "failed";
+				batchState.endedAt = Date.now();
+				batchState.errors.push(`Engine process exited with code ${code}`);
+			}
+			ctx.ui.notify(
+				`❌ Engine process exited unexpectedly (code ${code}).`,
+				"error",
+			);
+			updateWidget();
+		}
+		settle();
+	});
+
+	return child;
 }
 
 // ── TP-043 R002-2: Integration Executor Builder ─────────────────────
@@ -1292,9 +1386,9 @@ export default function (pi: ExtensionAPI) {
 	let orchWidgetCtx: ExtensionContext | undefined;
 	let latestMonitorState: MonitorState | null = null;
 
-	// ── TP-071: Active engine handle (currently unused — fork disabled) ──
-	// Will be restored when engine-worker ships as pre-compiled .js bundle.
-	let activeWorker: 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();
@@ -1911,8 +2005,8 @@ export default function (pi: ExtensionAPI) {
 			return ORCH_MESSAGES.pauseAlreadyPaused(orchBatchState.batchId);
 		}
 		orchBatchState.pauseSignal.paused = true;
-		// TP-071: Forward pause to engine process (disabled — fork not active)
-		// activeWorker?.send({ type: "pause" });
+		// TP-071: Forward pause to engine process (its pauseSignal is separate)
+		activeWorker?.send({ type: "pause" });
 		updateOrchWidget();
 		return ORCH_MESSAGES.pauseActivated(orchBatchState.batchId);
 	}
@@ -2102,10 +2196,16 @@ export default function (pi: ExtensionAPI) {
 			orchBatchState.pauseSignal.paused = true;
 			messages.push("  ✓ Pause signal set on in-memory batch state");
 		}
-		// TP-071: Forward pause to engine (disabled — fork not active)
-		if (false as boolean) {
-			// Will be restored when engine-worker ships as pre-compiled .js bundle
-			messages.push("  ✓ Pause signal forwarded to engine process");
+		// TP-071: Forward pause to engine and kill on hard abort
+		if (activeWorker) {
+			activeWorker.send({ type: "pause" });
+			if (hard) {
+				activeWorker.kill();
+				activeWorker = null;
+				messages.push("  ✓ Engine process killed (hard abort)");
+			} else {
+				messages.push("  ✓ Pause signal forwarded to engine process");
+			}
 		}
 
 		// Step 3: Check what we're aborting
@@ -3182,8 +3282,15 @@ 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: Kill engine process on session exit (disabled — fork not active)
-		// Will be restored when engine-worker ships as pre-compiled .js bundle
+		// TP-071: Kill engine process on session exit
+		if (activeWorker) {
+			try {
+				activeWorker.kill();
+				activeWorker = null;
+			} catch {
+				// Best effort — process may already be dead
+			}
+		}
 		try {
 			await deactivateSupervisor(pi, supervisorState);
 		} catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskplane",
-  "version": "0.20.5",
+  "version": "0.21.0",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",
@@ -43,6 +43,7 @@
     "@sinclair/typebox": "*"
   },
   "dependencies": {
+    "jiti": "^2.6.1",
     "yaml": "^2.4.0"
   },
   "license": "MIT",