taskplane 0.25.4 → 0.25.5

package/extensions/taskplane/agent-bridge-extension.ts

@@ -25,7 +25,8 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "@mariozechner/pi-ai";
 import { writeFileSync, readFileSync, existsSync, mkdirSync, renameSync, unlinkSync } from "fs";
 import { join, dirname } from "path";
-import { spawn as nodeSpawn, spawnSync } from "child_process";
+import { spawn as nodeSpawn } from "child_process";
+import { resolvePiCliPath, resolveTaskplaneAgentTemplate } from "./path-resolver.ts";
 import { randomBytes } from "crypto";
 import { buildExpansionRequestId, type SegmentExpansionRequest } from "./types.ts";
 
@@ -356,73 +357,22 @@ export default function (pi: ExtensionAPI) {
 	// The reviewer runs as a separate Pi process, writes feedback to
 	// .reviews/, and this tool returns the verdict to the worker.
 
-	/**
-	 * Resolve the Pi CLI entrypoint path (same logic as agent-host.ts).
-	 */
-	let _npmRootCache: string | null = null;
-	function getNpmGlobalRoot(): string {
-		if (_npmRootCache !== null) return _npmRootCache;
-		try {
-			const result = spawnSync("npm", ["root", "-g"], { encoding: "utf-8", timeout: 5000, shell: true });
-			_npmRootCache = result.stdout?.trim() || "";
-		} catch { _npmRootCache = ""; }
-		return _npmRootCache;
-	}
-
-	function resolvePiCli(): string {
-		const relPath = join("@mariozechner", "pi-coding-agent", "dist", "cli.js");
-		const candidates: string[] = [];
 
-		// Dynamic: npm root -g (covers nvm, Homebrew, volta, and all custom prefixes)
-		const npmRoot = getNpmGlobalRoot();
-		if (npmRoot) candidates.push(join(npmRoot, relPath));
-
-		// Well-known static paths
-		const home = process.env.HOME || process.env.USERPROFILE || "";
-		if (process.env.APPDATA) candidates.push(join(process.env.APPDATA, "npm", "node_modules", relPath));
-		if (home) {
-			candidates.push(join(home, "AppData", "Roaming", "npm", "node_modules", relPath));
-			candidates.push(join(home, ".npm-global", "lib", "node_modules", relPath));
-		}
-		candidates.push(join("/usr", "local", "lib", "node_modules", relPath));
-		candidates.push(join("/opt", "homebrew", "lib", "node_modules", relPath));
-
-		for (const c of candidates) {
-			if (existsSync(c)) return c;
-		}
-		throw new Error("Cannot find Pi CLI entrypoint. Run: npm root -g to verify your npm global path.");
-	}
 
 	/**
 	 * Load the reviewer system prompt from base template + local override.
+	 * Uses resolveTaskplaneAgentTemplate (path-resolver.ts) for all platform support (TP-157).
 	 */
 	function loadReviewerPrompt(): string {
-		const relPath = join("taskplane", "templates", "agents", "task-reviewer.md");
-		const candidates: string[] = [];
-
-		// Dynamic: npm root -g
-		const npmRoot = getNpmGlobalRoot();
-		if (npmRoot) candidates.push(join(npmRoot, relPath));
-
-		// Well-known static paths
-		const home = process.env.HOME || process.env.USERPROFILE || "";
-		if (process.env.APPDATA) candidates.push(join(process.env.APPDATA, "npm", "node_modules", relPath));
-		if (home) {
-			candidates.push(join(home, "AppData", "Roaming", "npm", "node_modules", relPath));
-			candidates.push(join(home, ".npm-global", "lib", "node_modules", relPath));
-		}
-		candidates.push(join("/usr", "local", "lib", "node_modules", relPath));
-		candidates.push(join("/opt", "homebrew", "lib", "node_modules", relPath));
-
 		let basePrompt = "You are a code reviewer. Read the request and write your review to the specified output file.";
-		for (const p of candidates) {
-			try {
-				if (!existsSync(p)) continue;
-				const raw = readFileSync(p, "utf-8");
+		try {
+			const templatePath = resolveTaskplaneAgentTemplate("task-reviewer");
+			if (existsSync(templatePath)) {
+				const raw = readFileSync(templatePath, "utf-8");
 				const fmEnd = raw.indexOf("---", 4);
-				if (fmEnd > 0) { basePrompt = raw.slice(fmEnd + 3).trim(); break; }
-			} catch { continue; }
-		}
+				if (fmEnd > 0) basePrompt = raw.slice(fmEnd + 3).trim();
+			}
+		} catch { /* fall through to default */ }
 		// Local override
 		const localPaths = [join(process.cwd(), ".pi", "agents", "task-reviewer.md"), join(process.cwd(), "agents", "task-reviewer.md")];
 		for (const p of localPaths) {
@@ -479,7 +429,7 @@ export default function (pi: ExtensionAPI) {
 		// Pre-clean stale reviewer state from prior interrupted review
 		removeReviewerState(taskFolder);
 		return new Promise((resolve) => {
-			const cliPath = resolvePiCli();
+			const cliPath = resolvePiCliPath();
 			const args = [
 				cliPath, "--mode", "rpc", "--no-session", "--no-extensions", "--no-skills",
 				"--tools", "read,write,edit,bash,grep,find,ls",

package/extensions/taskplane/agent-host.ts

@@ -20,7 +20,7 @@
  * @since TP-104
  */
 
-import { spawn, spawnSync, type ChildProcess } from "child_process";
+import { spawn, type ChildProcess } from "child_process";
 import {
 	readFileSync, writeFileSync, appendFileSync, mkdirSync,
 	existsSync, readdirSync, renameSync,
@@ -45,67 +45,12 @@ import {
 	writeRegistrySnapshot,
 } from "./process-registry.ts";
 import { appendMailboxAuditEvent } from "./mailbox.ts";
+import { resolvePiCliPath } from "./path-resolver.ts";
 
 // ── Pi CLI Resolution ────────────────────────────────────────────────
+// resolvePiCliPath() is imported from path-resolver.ts and re-exported below (TP-157)
 
-/**
- * Resolve the Pi CLI JS entrypoint for direct spawning.
- *
- * On Windows, `pi` resolves to a .CMD shim which cannot be spawned
- * with `shell: false`. This function resolves the underlying JS file.
- *
- * Resolution order:
- *   1. npm root -g (dynamic — covers nvm, Homebrew, volta, custom prefix)
- *   2. APPDATA/npm/node_modules/... (Windows)
- *   3. HOME/.npm-global/lib/node_modules/...
- *   4. /usr/local/lib/node_modules/...
- *   5. /opt/homebrew/lib/node_modules/... (macOS Homebrew)
- *
- * @returns Absolute path to the Pi CLI JS entrypoint
- * @throws Error if Pi CLI cannot be found
- *
- * @since TP-104
- */
-let _npmGlobalRootCache: string | null = null;
-function getNpmGlobalRoot(): string {
-	if (_npmGlobalRootCache !== null) return _npmGlobalRootCache;
-	try {
-		const result = spawnSync("npm", ["root", "-g"], { encoding: "utf-8", timeout: 5000, shell: true });
-		_npmGlobalRootCache = result.stdout?.trim() || "";
-	} catch {
-		_npmGlobalRootCache = "";
-	}
-	return _npmGlobalRootCache;
-}
-
-export function resolvePiCliPath(): string {
-	const relPath = join("@mariozechner", "pi-coding-agent", "dist", "cli.js");
-	const candidates: string[] = [];
-
-	// Dynamic first: covers nvm, Homebrew, volta, custom npm prefix
-	const npmRoot = getNpmGlobalRoot();
-	if (npmRoot) candidates.push(join(npmRoot, relPath));
-
-	// Well-known static fallbacks
-	const home = process.env.HOME || process.env.USERPROFILE || "";
-	if (process.env.APPDATA) candidates.push(join(process.env.APPDATA, "npm", "node_modules", relPath));
-	if (home) {
-		candidates.push(join(home, "AppData", "Roaming", "npm", "node_modules", relPath));
-		candidates.push(join(home, ".npm-global", "lib", "node_modules", relPath));
-	}
-	candidates.push(join("/usr", "local", "lib", "node_modules", relPath));
-	candidates.push(join("/opt", "homebrew", "lib", "node_modules", relPath));
-
-	for (const candidate of candidates) {
-		if (existsSync(candidate)) return candidate;
-	}
-
-	throw new Error(
-		"Cannot find Pi CLI entrypoint (cli.js). Ensure pi is installed globally via 'pi install'. " +
-		`npm root -g: ${npmRoot || "(not found)"}`,
-	);
-}
-
+export { resolvePiCliPath };
 // ── Conversation Payload Helpers (TP-111) ───────────────────────────────
 
 /** Maximum characters for conversation event text payloads. */

package/extensions/taskplane/execution.ts

@@ -4,102 +4,20 @@
  */
 import { readFileSync, existsSync, statSync, unlinkSync, mkdirSync, writeFileSync, copyFileSync } from "fs";
 import { access as fsAccess, readFile as fsReadFile, stat as fsStat } from "fs/promises";
-import { spawnSync } from "child_process";
 import { join, dirname, basename, resolve, relative, delimiter as pathDelimiter } from "path";
 import { userInfo } from "os";
 
 import { DONE_GRACE_MS, EXECUTION_POLL_INTERVAL_MS, ExecutionError, SESSION_SPAWN_RETRY_MAX } from "./types.ts";
 import type { AllocatedLane, AllocatedTask, DependencyGraph, LaneExecutionResult, LaneMonitorSnapshot, LaneTaskOutcome, LaneTaskStatus, MonitorState, MtimeTracker, OrchestratorConfig, ParsedTask, TaskMonitorSnapshot, WaveExecutionResult, WorkspaceConfig, ExecutionUnit, PacketPaths, RuntimeAgentId, RuntimeAgentRole, SupervisorAlertCallback } from "./types.ts";
 import { resolvePacketPaths, buildRuntimeAgentId } from "./types.ts";
-import { readRegistrySnapshot, readLaneSnapshot, isTerminalStatus, isProcessAlive } from "./process-registry.ts";
+import { readRegistrySnapshot, readLaneSnapshot, isTerminalStatus, isProcessAlive, detectOrphans, markOrphansCrashed } from "./process-registry.ts";
 import { allocateLanes } from "./waves.ts";
 import { resolveOperatorId } from "./naming.ts";
 import { runGit } from "./git.ts";
+import { resolveTaskplanePackageFile, resolveTaskplaneAgentTemplate } from "./path-resolver.ts";
 
 // ── Taskplane Package File Resolution ────────────────────────────────
-
-/**
- * Cached result of `npm root -g` to avoid repeated child process spawns.
- * null = not yet resolved, "" = resolution failed.
- */
-let _npmGlobalRoot: string | null = null;
-
-/**
- * Get the global npm root directory via `npm root -g`.
- * Result is cached for the process lifetime.
- */
-function getNpmGlobalRoot(): string {
-	if (_npmGlobalRoot !== null) return _npmGlobalRoot;
-	try {
-		const result = spawnSync("npm", ["root", "-g"], {
-			encoding: "utf-8",
-			timeout: 5000,
-			shell: true,
-		});
-		_npmGlobalRoot = result.stdout?.trim() || "";
-	} catch {
-		_npmGlobalRoot = "";
-	}
-	return _npmGlobalRoot;
-}
-
-/**
- * Resolve a file path within the taskplane package.
- *
- * Resolution order:
- *   1. Local project: {repoRoot}/{relPath} (for taskplane development)
- *   2. `npm root -g` based: {npmGlobalRoot}/taskplane/{relPath}
- *      (covers Homebrew, nvm, volta, pnpm, and any custom npm prefix)
- *   3. Well-known global npm paths (Windows/macOS/Linux):
- *      - {APPDATA}/npm/node_modules/taskplane/{relPath}
- *      - {HOME}/.npm-global/lib/node_modules/taskplane/{relPath}
- *      - /usr/local/lib/node_modules/taskplane/{relPath}
- *      - /opt/homebrew/lib/node_modules/taskplane/{relPath}
- *   4. Peer of pi's package: resolve from pi's binary location
- *
- * @param repoRoot - Absolute path to the project root
- * @param relPath  - Relative path within the taskplane package (e.g., "bin/rpc-wrapper.mjs")
- * @returns Absolute path to the resolved file
- */
-function resolveTaskplanePackageFile(repoRoot: string, relPath: string): string {
-	// 1. Local project (taskplane development)
-	const localPath = join(resolve(repoRoot), relPath);
-	if (existsSync(localPath)) return localPath;
-
-	const candidates: string[] = [];
-
-	// 2. Dynamic: `npm root -g` (covers ALL npm setups: nvm, Homebrew, volta, etc.)
-	const npmRoot = getNpmGlobalRoot();
-	if (npmRoot) {
-		candidates.push(join(npmRoot, "taskplane", relPath));
-	}
-
-	// 3. Well-known static paths
-	const home = process.env.HOME || process.env.USERPROFILE || "";
-	if (process.env.APPDATA) {
-		candidates.push(join(process.env.APPDATA, "npm", "node_modules", "taskplane", relPath));
-	}
-	if (home) {
-		candidates.push(join(home, "AppData", "Roaming", "npm", "node_modules", "taskplane", relPath));
-		candidates.push(join(home, ".npm-global", "lib", "node_modules", "taskplane", relPath));
-	}
-	candidates.push(join("/usr", "local", "lib", "node_modules", "taskplane", relPath));
-	candidates.push(join("/opt", "homebrew", "lib", "node_modules", "taskplane", relPath));
-
-	// 4. Peer of pi's package
-	try {
-		const piPath = process.argv[1] || "";
-		const piPkgDir = resolve(piPath, "..", "..");
-		candidates.push(join(piPkgDir, "..", "taskplane", relPath));
-	} catch { /* ignore */ }
-
-	for (const candidate of candidates) {
-		if (existsSync(candidate)) return candidate;
-	}
-
-	// Fallback: return the local path (will fail at spawn time with a clear error)
-	return localPath;
-}
+// getNpmGlobalRoot() and resolveTaskplanePackageFile() consolidated in path-resolver.ts (TP-157)
 
 // ── Task Runner Extension Path Resolution ────────────────────────────
 
@@ -911,7 +829,37 @@ export async function resolveTaskMonitorState(
 				sessionAlive = true;
 			}
 		} else {
-			sessionAlive = snap.status === "running";
+			// TP-159: Fast-fail path for ghost workers (issue #461).
+			// When the snapshot belongs to the current task but the lane-runner
+			// has stopped updating it and the agent's PID is confirmed dead,
+			// immediately set sessionAlive=false instead of waiting for the full
+			// stall timeout. This handles the case where a worker dies silently
+			// (OOM, segfault, parent crash) after writing its first snapshot:
+			//   snap.status stays "running", stallTimerStart stays null
+			//   (STATUS.md never written), so Priority 2 never fires without
+			//   this explicit dead-PID check.
+			// Conditions:
+			//   1. snap.updatedAt is stale beyond stallTimeoutMs/2
+			//   2. startup grace has elapsed (trackerAgeMs >= 60s)
+			//   3. agent is confirmed dead (registry marked crashed by orphan scan)
+			const trackerAgeMs = now - tracker.firstObservedAt;
+			if (
+				snap.updatedAt &&
+				(now - snap.updatedAt) > stallTimeoutMs / 2 &&
+				trackerAgeMs >= 60_000 &&
+				!isV2AgentAlive(sessionName, runtimeBackend, v2Context?.laneNumber)
+			) {
+				// Ghost worker confirmed: PID dead, snapshot stale beyond half the stall timeout
+				execLog("monitor", taskId, "ghost worker fast-fail — dead PID + stale snapshot", {
+					session: sessionName,
+					snapStaleMs: now - snap.updatedAt,
+					trackerAgeMs,
+					halfStallTimeoutMs: stallTimeoutMs / 2,
+				});
+				sessionAlive = false;
+			} else {
+				sessionAlive = snap.status === "running";
+			}
 		}
 	} else {
 		sessionAlive = isV2AgentAlive(sessionName, "v2", v2Context?.laneNumber);
@@ -1178,6 +1126,30 @@ export async function monitorLanes(
 			setV2LivenessRegistryCache(null);
 		}
 
+		// TP-159: Detect and mark orphaned workers each poll cycle.
+		// When a worker subprocess dies silently (OOM kill, segfault, parent
+		// crash) without going through the normal completion handshake, its
+		// registry manifest stays in a non-terminal status indefinitely.
+		// Scanning for dead PIDs here ensures list_active_agents, read_agent_status,
+		// and the dashboard all reflect reality within one poll interval.
+		if (runtimeBackend === "v2" && batchId) {
+			try {
+				const registry = readRegistrySnapshot(stateRootForRegistry ?? repoRoot, batchId);
+				if (registry) {
+					const orphans = detectOrphans(registry);
+					if (orphans.length > 0) {
+						markOrphansCrashed(stateRootForRegistry ?? repoRoot, batchId, orphans);
+						// Refresh cache so this poll cycle sees the updated crashed status
+						setV2LivenessRegistryCache(
+							readRegistrySnapshot(stateRootForRegistry ?? repoRoot, batchId)
+						);
+					}
+				}
+			} catch {
+				// Non-fatal — monitor loop must never throw
+			}
+		}
+
 		// Check pause signal
 		if (pauseSignal.paused) {
 			execLog("monitor", "ALL", "pause signal detected — stopping monitoring");
@@ -2126,15 +2098,11 @@ function parseAgentFile(filePath: string): { fm: Record<string, string>; body: s
  * @since TP-117
  */
 function loadBaseAgentPrompt(agentName: string): string {
-	// Use the same robust resolution as resolveTaskplanePackageFile, which
-	// handles all npm setups (nvm, Homebrew, volta, Windows, etc.) via
-	// npm root -g caching and well-known fallback paths.
-	// This avoids loadBaseAgentPrompt silently returning "" (which would
-	// cause the worker to skip reviews because the review_step instructions
-	// live in the base template, not the local .pi/agents/ override).
-	const relPath = join("templates", "agents", `${agentName}.md`);
+	// resolveTaskplaneAgentTemplate handles all npm setups (nvm, Homebrew, volta, Windows, etc.)
+	// via npm root -g caching and well-known fallback paths (see path-resolver.ts, TP-157).
+	// This avoids silently returning "" which would cause the worker to skip reviews.
 	try {
-		const resolved = resolveTaskplanePackageFile(process.cwd(), relPath);
+		const resolved = resolveTaskplaneAgentTemplate(agentName);
 		if (existsSync(resolved)) {
 			const def = parseAgentFile(resolved);
 			if (def?.body) return def.body;

package/extensions/taskplane/extension.ts

@@ -1914,6 +1914,39 @@ export default function (pi: ExtensionAPI) {
 			};
 		}
 
+		// TP-158: Reload config from disk so changes made after session start
+		// (e.g. creating .pi/taskplane-config.json mid-session) take effect
+		// immediately — fixes issue #460 where stale task_areas caused
+		// "Discovery had fatal errors" on first /orch run after config creation.
+		// Skip if a batch is already active to avoid swapping config mid-run.
+		const _activePhase = orchBatchState.phase;
+		const _isActiveBatch = _activePhase === "executing" || _activePhase === "launching"
+			|| _activePhase === "merging" || _activePhase === "planning";
+		if (!_isActiveBatch) {
+			try {
+				// Build everything into temporaries first, then commit atomically
+				// so a partial failure doesn't leave mixed-generation state.
+				const freshCtx = buildExecutionContext(ctx.cwd, loadOrchestratorConfig, loadTaskRunnerConfig);
+				let freshSupervisor: SupervisorConfig;
+				try {
+					freshSupervisor = loadSupervisorConfig(
+						freshCtx.repoRoot,
+						freshCtx.pointer?.configRoot,
+					);
+				} catch {
+					freshSupervisor = { ...DEFAULT_SUPERVISOR_CONFIG };
+				}
+				// Atomic commit — all or nothing
+				execCtx = freshCtx;
+				orchConfig = freshCtx.orchestratorConfig;
+				runnerConfig = freshCtx.taskRunnerConfig;
+				supervisorConfig = freshSupervisor;
+			} catch {
+				// Non-fatal — if reload fails, proceed with existing config.
+				// The existing config guard below will handle a null execCtx.
+			}
+		}
+
 		if (!execCtx) {
 			return {
 				message: getExecCtxInitErrorMessage(),

package/extensions/taskplane/path-resolver.ts

@@ -0,0 +1,233 @@
+/**
+ * Path Resolver — Consolidated npm global root detection and package/tool path resolution.
+ *
+ * This module is the single source of truth for resolving paths to globally-installed
+ * npm packages (taskplane and the pi coding agent CLI). It was created to eliminate
+ * three duplicate implementations that previously existed in execution.ts, agent-host.ts,
+ * and agent-bridge-extension.ts.
+ *
+ * ## Why this module exists
+ *
+ * macOS-specific bugs (#472, #474) were caused by hardcoded path lists that missed
+ * Homebrew (`/opt/homebrew`) and contained ESM-unsafe `require()` calls. Each fix had
+ * to be applied to multiple files, risking future drift. A single module eliminates that.
+ *
+ * ## Platform coverage
+ *
+ * - **Windows** — npm global root is typically `%APPDATA%\npm\node_modules` or a custom
+ *   prefix. Static fallbacks cover both the APPDATA env var path and the HOME-relative
+ *   equivalent (`AppData\Roaming\npm\node_modules`).
+ *
+ * - **macOS** — Multiple valid npm setups are covered:
+ *   - System Node via Homebrew: `/opt/homebrew/lib/node_modules`
+ *   - System Node (legacy): `/usr/local/lib/node_modules`
+ *   - nvm, volta, or custom prefix: resolved dynamically via `npm root -g`
+ *   - Custom global prefix: `~/.npm-global/lib/node_modules`
+ *
+ * - **Linux** — System Node (`/usr/local/lib/node_modules`), nvm, volta, and custom
+ *   prefixes are all covered dynamically via `npm root -g`.
+ *
+ * ## Resolution strategy
+ *
+ * `npm root -g` is the **primary** resolution path because it covers every npm setup
+ * (nvm, Homebrew, volta, pnpm global, and any custom `--prefix`) with a single call.
+ * Static fallbacks exist only for environments where `npm` is not on PATH, which is
+ * uncommon but can happen in certain CI containers or restricted environments.
+ *
+ * The `npm root -g` result is module-level cached because:
+ *   1. It is called from multiple callsites per process.
+ *   2. The result never changes within a process lifetime.
+ *   3. Spawning a subprocess on every call would be expensive.
+ *
+ * @module taskplane/path-resolver
+ * @since TP-157
+ */
+
+import { spawnSync } from "child_process";
+import { existsSync } from "fs";
+import { join, resolve } from "path";
+
+// ── Module-level cache ──────────────────────────────────────────────
+
+/**
+ * Cached result of `npm root -g`.
+ * `null` = not yet resolved; `""` = resolution failed.
+ */
+let _npmGlobalRoot: string | null = null;
+
+// ── Exported functions ──────────────────────────────────────────────
+
+/**
+ * Get the global npm root directory via `npm root -g`.
+ *
+ * The result is cached at module level for the process lifetime, so repeated
+ * calls are free after the first.
+ *
+ * @returns Absolute path to the npm global `node_modules` directory,
+ *          or `""` if the call fails (npm not on PATH, subprocess error, etc.).
+ *          Never throws.
+ *
+ * @platform Windows — `shell: true` is required because `npm` resolves to
+ *           `npm.cmd`, a Windows batch script that cannot be spawned without a shell.
+ */
+export function getNpmGlobalRoot(): string {
+	if (_npmGlobalRoot !== null) return _npmGlobalRoot;
+	try {
+		const result = spawnSync("npm", ["root", "-g"], {
+			encoding: "utf-8",
+			timeout: 5000,
+			// shell: true is mandatory on Windows — npm resolves to npm.cmd
+			shell: true,
+		});
+		_npmGlobalRoot = result.stdout?.trim() || "";
+	} catch {
+		_npmGlobalRoot = "";
+	}
+	return _npmGlobalRoot;
+}
+
+/**
+ * Resolve the absolute path to the Pi coding agent CLI entrypoint (`cli.js`).
+ *
+ * The Pi CLI is installed as `@mariozechner/pi-coding-agent`. On Windows, invoking
+ * `pi` directly executes a `.CMD` shim that cannot be spawned with `shell: false`.
+ * This function locates the underlying `dist/cli.js` so callers can spawn it with
+ * `node` directly, without a shell intermediary.
+ *
+ * Resolution order:
+ *   1. `npm root -g` result (dynamic — covers all setups: nvm, Homebrew, volta, etc.)
+ *   2. `%APPDATA%\npm\node_modules\...` (Windows, APPDATA env var)
+ *   3. `%USERPROFILE%\AppData\Roaming\npm\node_modules\...` (Windows, HOME-relative)
+ *   4. `~/.npm-global/lib/node_modules/...` (macOS/Linux custom global prefix)
+ *   5. `/usr/local/lib/node_modules/...` (macOS system Node, Linux)
+ *   6. `/opt/homebrew/lib/node_modules/...` (macOS Homebrew)
+ *
+ * @returns Absolute path to `@mariozechner/pi-coding-agent/dist/cli.js`
+ * @throws  {Error} If the CLI entrypoint cannot be found in any known location.
+ *          The error message includes the `npm root -g` value for diagnosis.
+ */
+export function resolvePiCliPath(): string {
+	const relPath = join("@mariozechner", "pi-coding-agent", "dist", "cli.js");
+	const candidates: string[] = [];
+
+	// 1. Dynamic: npm root -g (covers nvm, Homebrew, volta, custom npm prefix, etc.)
+	const npmRoot = getNpmGlobalRoot();
+	if (npmRoot) candidates.push(join(npmRoot, relPath));
+
+	// 2-3. Static Windows fallbacks
+	const home = process.env.HOME || process.env.USERPROFILE || "";
+	if (process.env.APPDATA) {
+		candidates.push(join(process.env.APPDATA, "npm", "node_modules", relPath));
+	}
+	if (home) {
+		candidates.push(join(home, "AppData", "Roaming", "npm", "node_modules", relPath));
+		// 4. macOS/Linux custom global prefix
+		candidates.push(join(home, ".npm-global", "lib", "node_modules", relPath));
+	}
+	// 5. macOS system Node / Linux
+	candidates.push(join("/usr", "local", "lib", "node_modules", relPath));
+	// 6. macOS Homebrew
+	candidates.push(join("/opt", "homebrew", "lib", "node_modules", relPath));
+
+	for (const candidate of candidates) {
+		if (existsSync(candidate)) return candidate;
+	}
+
+	throw new Error(
+		"Cannot find Pi CLI entrypoint (@mariozechner/pi-coding-agent/dist/cli.js). " +
+		"Ensure the pi coding agent is installed globally via 'npm install -g @mariozechner/pi-coding-agent'. " +
+		`npm root -g returned: ${npmRoot || "(empty — npm may not be on PATH)"}`,
+	);
+}
+
+/**
+ * Resolve the path to a file within the taskplane npm package.
+ *
+ * This handles both local development (running from the taskplane repo itself)
+ * and the installed-package case (taskplane installed globally via npm).
+ *
+ * Resolution order:
+ *   1. `join(repoRoot, relPath)` — local development (taskplane's own repo)
+ *   2. `npm root -g` result: `{npmGlobalRoot}/taskplane/{relPath}` (dynamic, all setups)
+ *   3. `{APPDATA}/npm/node_modules/taskplane/{relPath}` (Windows)
+ *   4. `{HOME}/AppData/Roaming/npm/node_modules/taskplane/{relPath}` (Windows alt)
+ *   5. `{HOME}/.npm-global/lib/node_modules/taskplane/{relPath}` (macOS/Linux custom prefix)
+ *   6. `/usr/local/lib/node_modules/taskplane/{relPath}` (macOS system Node, Linux)
+ *   7. `/opt/homebrew/lib/node_modules/taskplane/{relPath}` (macOS Homebrew)
+ *   8. Peer of pi's package (adjacent to `process.argv[1]`)
+ *
+ * @param repoRoot - Absolute path to the project root (used for local dev check)
+ * @param relPath  - Relative path within the taskplane package, e.g.
+ *                   `"extensions/task-runner.ts"` or `"templates/agents/task-worker.md"`
+ * @returns Absolute path to the resolved file. If not found in any location,
+ *          returns the local path (`join(repoRoot, relPath)`) as a fallback — callers
+ *          will fail at use time with a clear "file not found" error.
+ */
+export function resolveTaskplanePackageFile(repoRoot: string, relPath: string): string {
+	// 1. Local development — taskplane's own repo
+	const localPath = join(resolve(repoRoot), relPath);
+	if (existsSync(localPath)) return localPath;
+
+	const candidates: string[] = [];
+
+	// 2. Dynamic: npm root -g (covers ALL npm setups: nvm, Homebrew, volta, etc.)
+	const npmRoot = getNpmGlobalRoot();
+	if (npmRoot) {
+		candidates.push(join(npmRoot, "taskplane", relPath));
+	}
+
+	// 3-7. Well-known static paths
+	const home = process.env.HOME || process.env.USERPROFILE || "";
+	if (process.env.APPDATA) {
+		candidates.push(join(process.env.APPDATA, "npm", "node_modules", "taskplane", relPath));
+	}
+	if (home) {
+		candidates.push(join(home, "AppData", "Roaming", "npm", "node_modules", "taskplane", relPath));
+		candidates.push(join(home, ".npm-global", "lib", "node_modules", "taskplane", relPath));
+	}
+	candidates.push(join("/usr", "local", "lib", "node_modules", "taskplane", relPath));
+	candidates.push(join("/opt", "homebrew", "lib", "node_modules", "taskplane", relPath));
+
+	// 8. Peer of pi's package (look adjacent to pi's CLI entrypoint)
+	try {
+		const piPath = process.argv[1] || "";
+		const piPkgDir = resolve(piPath, "..", "..");
+		candidates.push(join(piPkgDir, "..", "taskplane", relPath));
+	} catch { /* ignore — process.argv[1] may be undefined in test contexts */ }
+
+	for (const candidate of candidates) {
+		if (existsSync(candidate)) return candidate;
+	}
+
+	// Fallback: return the local path. Callers will fail with a clear error at use time.
+	return localPath;
+}
+
+/**
+ * Resolve the path to a taskplane agent template file.
+ *
+ * Convenience wrapper around {@link resolveTaskplanePackageFile} for the
+ * common case of locating a file in `templates/agents/`.
+ *
+ * Used by `loadBaseAgentPrompt` (execution.ts) and `loadReviewerPrompt`
+ * (agent-bridge-extension.ts) to locate the base agent prompt templates
+ * that ship with the taskplane package.
+ *
+ * @param agentName - Agent template name without extension, e.g. `"task-worker"`,
+ *                    `"task-reviewer"`, `"task-merger"`
+ * @returns Absolute path to `templates/agents/{agentName}.md` within the
+ *          resolved taskplane package root.
+ *
+ * @example
+ * ```ts
+ * const templatePath = resolveTaskplaneAgentTemplate("task-worker");
+ * // → "/usr/local/lib/node_modules/taskplane/templates/agents/task-worker.md"
+ * //   (or local dev path, or any other resolved location)
+ * ```
+ */
+export function resolveTaskplaneAgentTemplate(agentName: string): string {
+	return resolveTaskplanePackageFile(
+		process.cwd(),
+		join("templates", "agents", `${agentName}.md`),
+	);
+}

package/package.json

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