taskplane 0.30.2 → 0.30.4

package/README.md

@@ -1,6 +1,6 @@
 # Taskplane
 
-Multi-agent AI orchestration for coding with [pi](https://github.com/badlogic/pi-mono) — parallel task execution, mono- and poly-repo support, fresh-context worker loops, cross-model reviews, automated merges and a killer dashboard! 
+Multi-agent AI orchestration for coding with [pi](https://github.com/earendil-works/pi) — parallel task execution, mono- and poly-repo support, fresh-context worker loops, cross-model reviews, automated merges and a killer dashboard! 
 
 > **Status:** Initial release.
 
@@ -50,7 +50,7 @@ Taskplane is a pi package. You need Node.js 22+, pi and Git installed first.
 | Dependency | Required | Notes |
 |-----------|----------|-------|
 | [Node.js](https://nodejs.org/) ≥ 22 | Yes | Runtime |
-| [pi](https://github.com/badlogic/pi-mono) | Yes | Agent framework |
+| [pi](https://github.com/earendil-works/pi) | Yes | Agent framework |
 | [Git](https://git-scm.com/) | Yes | Version control, worktrees |
 
 IMPORTANT: If you just installed pi, make sure you've configured at least one model provider and tested before installing Taskplane.
@@ -61,6 +61,26 @@ IMPORTANT: If you just installed pi, make sure you've configured at least one mo
 pi install npm:taskplane
 ```
 
+As of pi `0.75.0`, this installs Taskplane into pi's private extension directory (`~/.pi/agent/npm/node_modules/`) rather than the system npm-global root. To make the `taskplane` CLI available on your shell PATH, add pi's bin dir once:
+
+```bash
+# bash / zsh
+echo 'export PATH="$HOME/.pi/agent/npm/node_modules/.bin:$PATH"' >> ~/.bashrc   # or ~/.zshrc
+```
+
+```powershell
+# PowerShell
+[Environment]::SetEnvironmentVariable(
+  "PATH",
+  "$HOME\.pi\agent\npm\node_modules\.bin;" + [Environment]::GetEnvironmentVariable("PATH", "User"),
+  "User"
+)
+```
+
+With Pi's bin dir on PATH, `pi update` keeps Taskplane current automatically — there's no second update command to remember.
+
+> **Note for users who previously ran `npm install -g taskplane`:** That puts a second copy of Taskplane in your system npm-global, separate from pi's private copy. The two copies drift independently (`pi update` only refreshes the pi-private one), and your shell will resolve `taskplane` to whichever is earlier on PATH. Run `taskplane doctor` — it now detects this duplication and prints a remediation. The fix is `npm uninstall -g taskplane` plus the PATH change above.
+
 ### Option B: Single Project-Local Install
 
 ```bash
@@ -68,6 +88,8 @@ cd my-project
 pi install -l npm:taskplane
 ```
 
+Project-local installs land in `.pi/npm/node_modules/`. Either invoke via `npx taskplane <cmd>`, run the binary directly at `.pi/npm/node_modules/.bin/taskplane`, or add that dir to PATH (project-scoped — e.g. via a `.envrc` if you use direnv).
+
 ## Quickstart
 
 ### 1. Initialize a project (to scaffold settings)

package/bin/taskplane.mjs

@@ -2789,6 +2789,53 @@ function cmdDoctor() {
 		`  ${OK} taskplane package installed ${c.dim}(v${pkgVersion}, ${installType})${c.reset}`,
 	);
 
+	// Duplication check: when both the Pi-private and the npm-global copies
+	// exist with different versions, `pi update` only refreshes the Pi-private
+	// one and the system-wide CLI silently drifts behind. Surface this clearly
+	// so operators don't run a stale CLI thinking `pi update` covered it.
+	// Background: Pi 0.75.0 (2026-05-17) moved user-scoped pi packages from
+	// npm's global root to `~/.pi/agent/npm/` to avoid system-Node permission
+	// errors. Users who installed via `npm install -g taskplane` before that
+	// landed (or who installed via both paths) end up with two on-disk copies.
+	let duplicationDetected = false;
+	const duplication = detectDuplicateTaskplaneInstall();
+	if (duplication) {
+		duplicationDetected = true;
+		console.log();
+		console.log(`  ${WARN} taskplane is installed in TWO locations with different versions:`);
+		for (const loc of duplication.locations) {
+			console.log(
+				`     ${c.dim}${loc.label}:${c.reset} v${loc.version}  ${c.dim}(${loc.path})${c.reset}`,
+			);
+		}
+		console.log(
+			`     ${c.dim}→ ${c.reset}\`pi update\`${c.dim} only refreshes the Pi-private copy.${c.reset}`,
+		);
+		console.log(
+			`     ${c.dim}→ Recommended fix: drop the npm-global copy and put Pi's bin dir on PATH:${c.reset}`,
+		);
+		console.log(`     ${c.cyan}    npm uninstall -g taskplane${c.reset}`);
+		// Platform-aware PATH guidance: PowerShell on Windows, bash/zsh elsewhere.
+		// Linux & macOS users running PowerShell can still copy the bash form;
+		// Windows users running Git Bash can still copy the PowerShell form. The
+		// platform check picks the line most likely to match a fresh shell on
+		// the host OS so the inline copy/paste path is one-line on the common
+		// case.
+		if (process.platform === "win32") {
+			console.log(
+				`     ${c.cyan}    $env:PATH = "$HOME\\.pi\\agent\\npm\\node_modules\\.bin;" + $env:PATH${c.reset}  ${c.dim}# PowerShell, add to $PROFILE${c.reset}`,
+			);
+			console.log(
+				`     ${c.dim}    or, for Git Bash:${c.reset} ${c.cyan}export PATH="$HOME/.pi/agent/npm/node_modules/.bin:$PATH"${c.reset}  ${c.dim}# ~/.bashrc${c.reset}`,
+			);
+		} else {
+			console.log(
+				`     ${c.cyan}    export PATH="$HOME/.pi/agent/npm/node_modules/.bin:$PATH"${c.reset}  ${c.dim}# add to ~/.bashrc / ~/.zshrc${c.reset}`,
+			);
+		}
+		issues++;
+	}
+
 	if (isWorkspaceMode) {
 		console.log();
 		if (wsResult.error) {
@@ -3315,9 +3362,21 @@ function cmdDoctor() {
 	if (issues === 0) {
 		console.log(`${OK} ${c.green}All checks passed!${c.reset}\n`);
 	} else {
-		console.log(
-			`${FAIL} ${issues} issue(s) found. Run ${c.cyan}taskplane init${c.reset} to fix config issues.\n`,
-		);
+		// Each check above prints its own inline remediation hint, so the
+		// summary points back to those rather than recommending a single
+		// generic fix. The previous summary always recommended
+		// `taskplane init`, which was misleading when the underlying issue
+		// was a duplicate install (whose remediation is
+		// `npm uninstall -g taskplane`, not init).
+		if (duplicationDetected) {
+			console.log(
+				`${FAIL} ${issues} issue(s) found. See remediation hints above (${c.cyan}npm uninstall -g taskplane${c.reset} for the duplicate install).\n`,
+			);
+		} else {
+			console.log(
+				`${FAIL} ${issues} issue(s) found. See remediation hints above; run ${c.cyan}taskplane init${c.reset} to fix config issues.\n`,
+			);
+		}
 		process.exit(1);
 	}
 }
@@ -3332,17 +3391,28 @@ function cmdVersion() {
 	console.log(`\ntaskplane ${c.bold}v${pkgVersion}${c.reset}`);
 	console.log(`  Package:  ${installType}`);
 
-	// Check for project config
+	// Check for project config. Only render the `version` / `installedAt`
+	// fields when they're actually present and non-empty — some marker files
+	// (e.g. taskplane's own source repo, where `.pi/taskplane.json` carries
+	// only migration history rather than init metadata) would otherwise
+	// produce the user-visible "vundefined, initialized unknown" placeholders.
 	const projectRoot = process.cwd();
 	const tpJson = path.join(projectRoot, ".pi", "taskplane.json");
 	if (fs.existsSync(tpJson)) {
 		try {
 			const info = JSON.parse(fs.readFileSync(tpJson, "utf-8"));
-			console.log(
-				`  Config:   .pi/taskplane.json (v${info.version}, initialized ${info.installedAt?.slice(0, 10) || "unknown"})`,
-			);
+			const parts = [];
+			if (typeof info.version === "string" && info.version.length > 0) {
+				parts.push(`v${info.version}`);
+			}
+			if (typeof info.installedAt === "string" && info.installedAt.length > 0) {
+				parts.push(`initialized ${info.installedAt.slice(0, 10)}`);
+			}
+			const suffix =
+				parts.length > 0 ? ` (${parts.join(", ")})` : ` ${c.dim}(metadata only)${c.reset}`;
+			console.log(`  Config:   .pi/taskplane.json${suffix}`);
 		} catch {
-			console.log(`  Config:   .pi/taskplane.json (unreadable)`);
+			console.log(`  Config:   .pi/taskplane.json ${c.dim}(unreadable)${c.reset}`);
 		}
 	} else {
 		console.log(`  Config:   ${c.dim}not initialized (run taskplane init)${c.reset}`);
@@ -3366,6 +3436,82 @@ function getPackageVersion() {
 	}
 }
 
+/**
+ * Detect a duplicate taskplane install: one copy at Pi's private extension
+ * directory (`~/.pi/agent/npm/node_modules/taskplane/`) and another at the
+ * system npm-global root, with DIFFERENT versions. Same-version installs
+ * are harmless and intentionally not flagged (they may drift later but
+ * aren't a problem in the present tense).
+ *
+ * Returns null when there's no detectable duplication, or an object
+ * describing the two locations + their versions when there is.
+ *
+ * Best-effort: silently returns null if `npm root -g` is unreachable or
+ * either package.json is unreadable, since the rest of `taskplane doctor`
+ * should never crash on a side check.
+ *
+ * Background: Pi 0.75.0 (2026-05-17) moved user-scoped pi packages from
+ * npm's global root to `~/.pi/agent/npm/` to avoid permission errors with
+ * system-managed Node installs (Pi changelog: "Fixed user-scoped npm pi
+ * packages to install under `~/.pi/agent/npm/` instead of npm's global
+ * package root"). Users who had previously run `npm install -g taskplane`
+ * (or who continue to do so per older docs) now have two on-disk copies
+ * that drift independently: `pi update` only refreshes the Pi-private one.
+ */
+function detectDuplicateTaskplaneInstall() {
+	const piPrivatePath = path.join(homedir(), ".pi", "agent", "npm", "node_modules", "taskplane");
+
+	let npmRootGlobal = null;
+	try {
+		// 5s timeout guards against the rare case where `npm` is on PATH but
+		// hangs (slow registry probe, misconfigured custom prefix, etc.).
+		// `taskplane doctor` is a diagnostic — it should never make the CLI
+		// itself feel hung. On timeout, execSync throws and we fall back to
+		// the catch branch, returning null and silently skipping the
+		// duplication check (best-effort by design).
+		npmRootGlobal = execSync("npm root -g", {
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+			timeout: 5000,
+		})
+			.toString()
+			.trim();
+	} catch {
+		return null;
+	}
+	if (!npmRootGlobal) return null;
+	const npmGlobalPath = path.join(npmRootGlobal, "taskplane");
+
+	// Skip if Pi-private and npm-global resolve to the same path on disk.
+	// This can happen on installs where Pi hasn't (yet) migrated to its
+	// private directory or where the two paths point at the same install.
+	if (path.resolve(piPrivatePath) === path.resolve(npmGlobalPath)) return null;
+
+	const candidates = [
+		{ path: piPrivatePath, label: "Pi-private" },
+		{ path: npmGlobalPath, label: "npm-global" },
+	];
+
+	const found = [];
+	for (const candidate of candidates) {
+		try {
+			const pkgJsonPath = path.join(candidate.path, "package.json");
+			if (!fs.existsSync(pkgJsonPath)) continue;
+			const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+			if (typeof pkg.version !== "string" || pkg.version.length === 0) continue;
+			found.push({ path: candidate.path, label: candidate.label, version: pkg.version });
+		} catch {
+			/* unreadable — skip this candidate */
+		}
+	}
+
+	// Need both copies to be a duplication. Same-version pair is not flagged.
+	if (found.length < 2) return null;
+	if (found[0].version === found[1].version) return null;
+
+	return { locations: found };
+}
+
 // ─── dashboard ──────────────────────────────────────────────────────────────
 
 function cmdDashboard(args) {

package/extensions/taskplane/supervisor.ts

@@ -2020,7 +2020,16 @@ export function presentBatchSummary(
 		(batchState.failedTasks > 0 ? `- **Failed:** ${batchState.failedTasks} task(s)\n` : "") +
 		`\nFull summary written to \`.pi/supervisor/${filename}\`.`;
 
-	pi.sendMessage(
+	// #597 (post-Sage-review): `presentBatchSummary` is a terminal best-effort
+	// operation, and it can be reached from a timer-origin call chain via
+	// `startHeartbeat → deactivateSupervisor → (state.pendingSummaryDeps)`.
+	// If the captured `pi` handle has gone stale by the time the heartbeat
+	// fires, an unwrapped `pi.sendMessage` here re-introduces the exact
+	// uncaughtException pattern #597 is meant to prevent. Use the same
+	// never-throw wrapper as the timer call sites: deliver the message if
+	// pi is healthy, drop it silently if pi is stale.
+	safeSendMessageFromTimer(
+		pi,
 		{
 			customType: "supervisor-batch-summary",
 			content: [{ type: "text", text: conciseText }],
@@ -3037,6 +3046,23 @@ export async function activateSupervisor(
 	};
 	writeLockfile(stateRoot, lock);
 
+	// #597: Defensive teardown before installing new timers.
+	//
+	// `state` is a mutable singleton that persists across activate/deactivate
+	// cycles. In re-activation paths (a previous activation that didn't go
+	// through `deactivateSupervisor` cleanly, session churn after takeover,
+	// etc.) `state.heartbeatTimer` and `state.eventTailer` may still reference
+	// running timers that captured a now-stale `pi` handle. If we just
+	// reassign `state.heartbeatTimer = startHeartbeat(...)` the previous
+	// timer is orphaned — still ticking, still holding the stale `pi`, and
+	// at the next tick its `pi.sendMessage()` call throws `assertActive` and
+	// crashes the host process. Tear down explicitly before replacing.
+	stopEventTailer(state.eventTailer);
+	if (state.heartbeatTimer) {
+		clearInterval(state.heartbeatTimer);
+		state.heartbeatTimer = null;
+	}
+
 	// Start heartbeat timer — updates lockfile every 30s, detects takeover
 	state.heartbeatTimer = startHeartbeat(stateRoot, state, pi);
 
@@ -3710,6 +3736,87 @@ export function buildTakeoverSummary(stateRoot: string, batchState: PersistedBat
  *
  * @since TP-041
  */
+
+// ── Stale extension-context guard (#597) ──────────────────────────────
+//
+// Pi throws "This extension ctx is stale after session replacement or reload."
+// from `assertActive` when an extension uses a captured `pi` handle after
+// `ctx.newSession()`, `ctx.fork()`, `ctx.switchSession()`, or `ctx.reload()`.
+// Background timers in this file (`startHeartbeat`, `startEventTailer`)
+// capture `pi` in a closure and call `pi.sendMessage()` at arbitrary times;
+// when the captured handle goes stale between timer ticks, an uncaught
+// throw from `pi.sendMessage()` becomes a process-fatal `uncaughtException`
+// that kills the entire Pi process — issue #597.
+//
+// `isStaleExtensionCtx` and `safeSendMessageFromTimer` together harden the
+// timer call sites: stale-ctx errors are recognized and swallowed (the timer
+// caller then stops itself), other errors are logged to stderr but do not
+// propagate. The supervisor surrenders its UI surface gracefully instead of
+// taking Pi down.
+
+/**
+ * Returns true when `err` is Pi's distinctive stale-extension-ctx error.
+ *
+ * Matched by error-message substring rather than by class identity because
+ * the error class is not exported by `@earendil-works/pi-coding-agent` and
+ * the message text is the stable, documented contract
+ * (`core/extensions/loader.js:assertActive`).
+ *
+ * Defensive against non-Error throws (string throws, null, undefined, etc.)
+ * which are not stale-ctx errors and should propagate to the caller's
+ * normal error path — we only swallow the specific Pi case.
+ *
+ * @since #597
+ */
+export function isStaleExtensionCtx(err: unknown): boolean {
+	if (err === null || err === undefined) return false;
+	// Read message off either an Error instance or a plain object with .message
+	const message =
+		typeof err === "object" && err !== null && "message" in err
+			? String((err as { message: unknown }).message ?? "")
+			: typeof err === "string"
+				? err
+				: "";
+	return message.includes("This extension ctx is stale");
+}
+
+/**
+ * `pi.sendMessage()` wrapper for timer-context callers (heartbeat / event
+ * tailer / digest timer).
+ *
+ * Returns `true` on success, `false` when the call was swallowed because
+ * the extension context has gone stale (per `isStaleExtensionCtx`). Other
+ * exceptions are logged via `console.error` but also do not propagate —
+ * the timer caller stays alive and continues, since the safe-default for a
+ * background timer in a long-running process is to keep ticking rather
+ * than crash the host. Callers should treat a `false` return as "Pi has
+ * replaced us; stop trying" and clear their own interval.
+ *
+ * @since #597
+ */
+export function safeSendMessageFromTimer(
+	pi: ExtensionAPI,
+	message: Parameters<ExtensionAPI["sendMessage"]>[0],
+	options?: Parameters<ExtensionAPI["sendMessage"]>[1],
+): boolean {
+	try {
+		pi.sendMessage(message, options);
+		return true;
+	} catch (err) {
+		if (isStaleExtensionCtx(err)) {
+			// Pi has replaced us. The timer caller will see `false` and stop.
+			return false;
+		}
+		// Unexpected error — log for diagnosis but do not crash the host.
+		console.error(
+			`[supervisor] pi.sendMessage from timer callback threw: ${
+				err instanceof Error ? err.message : String(err)
+			}`,
+		);
+		return true; // not stale; let the caller continue ticking
+	}
+}
+
 export function startHeartbeat(
 	stateRoot: string,
 	state: SupervisorState,
@@ -3731,9 +3838,14 @@ export function startHeartbeat(
 			// Read current lockfile to detect force takeover — async (TP-070)
 			const currentLock = await readLockfileAsync(stateRoot);
 			if (currentLock && currentLock.sessionId !== sessionId) {
-				// Another session has taken over — yield gracefully
+				// Another session has taken over — yield gracefully.
+				// #597: the captured `pi` handle may be stale at this point;
+				// use safeSendMessageFromTimer so a stale-ctx throw cannot
+				// escape and become an uncaughtException that kills the
+				// whole Pi process.
 				clearInterval(timer);
-				pi.sendMessage(
+				safeSendMessageFromTimer(
+					pi,
 					{
 						customType: "supervisor-yield",
 						content: [
@@ -4444,7 +4556,12 @@ export function startEventTailer(
 			setStatus("supervisor", `🔀 ${statusText}`);
 		}
 
-		pi.sendMessage(
+		// #597: guard against stale-ctx throws from the captured `pi` handle.
+		// If Pi has replaced us between event-tailer ticks, swallow the throw
+		// and stop the tailer rather than letting an uncaughtException kill
+		// the Pi process.
+		const ok = safeSendMessageFromTimer(
+			pi,
 			{
 				customType: "supervisor-event",
 				content: [{ type: "text", text }],
@@ -4452,6 +4569,9 @@ export function startEventTailer(
 			},
 			{ triggerTurn: true },
 		);
+		if (!ok) {
+			stopEventTailer(tailer);
+		}
 	};
 
 	// ── TP-043: Integration is triggered by triggerSupervisorIntegration() ──

package/package.json

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