taskplane 0.30.3 → 0.30.5

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.

package/extensions/taskplane/context-repair.ts

@@ -0,0 +1,158 @@
+/**
+ * In-flight tool_use/tool_result ordering repair — issue #621 (defense in depth).
+ *
+ * The supervisor injects `custom` display messages via pi.sendMessage(). Any
+ * such injection that lands while the interactive agent has a tool call in
+ * flight splices a message BETWEEN an assistant `tool_use` and its
+ * `toolResult`. Anthropic then rejects the request:
+ *
+ *   400 messages.N.content.M: unexpected `tool_use_id` found in `tool_result`
+ *   blocks ... Each `tool_result` block must have a corresponding `tool_use`
+ *   block in the previous message.
+ *
+ * The batch-end epilogue gate (supervisor-dispatch.ts) prevents the most common
+ * source, but the supervisor has many other background `pi.sendMessage(...,
+ * {triggerTurn:false})` sites (integration progress/result, heartbeat, routing)
+ * that can splice the same way. Rather than gate each one, this module repairs
+ * the ORDERING of the outgoing message array on the pi `context` event, which
+ * fires before every provider request (`transformContext`, on the pi-internal
+ * AgentMessage[] before convertToLlm). Each assistant's tool results are pulled
+ * to immediately follow it (in tool-call order); any spliced-in `custom`/`user`
+ * messages move to after the tool-result group. The request is therefore always
+ * valid regardless of where a stray message was appended, and a mistimed
+ * injection can never wedge the session.
+ *
+ * This does not mutate the persisted session tree — it only transforms the
+ * per-request context — so it is safe, idempotent, and self-correcting across
+ * reloads.
+ */
+
+interface ToolCallBlock {
+	type: string;
+	id?: string;
+	[key: string]: unknown;
+}
+interface AgentMessageLike {
+	role?: string;
+	content?: unknown;
+	toolCallId?: string;
+	[key: string]: unknown;
+}
+
+function toolUseIds(msg: AgentMessageLike): string[] {
+	if (!msg || msg.role !== "assistant" || !Array.isArray(msg.content)) return [];
+	const ids: string[] = [];
+	for (const block of msg.content as ToolCallBlock[]) {
+		if (
+			block &&
+			typeof block === "object" &&
+			block.type === "toolCall" &&
+			typeof block.id === "string"
+		) {
+			ids.push(block.id);
+		}
+	}
+	return ids;
+}
+
+/**
+ * Reorder `messages` so every assistant `tool_use` is immediately followed by
+ * its matching `toolResult`(s), relocating any spliced-in non-tool messages to
+ * after the tool-result group.
+ *
+ * Robustness (Sage #621 review):
+ * - Duplicate `toolResult` messages sharing a `toolCallId` are all preserved
+ *   (queue-based grouping, not last-wins), so repair never drops data.
+ * - Emitted results are tracked by message identity, not by id.
+ * - Also repairs the result-before-assistant shape: a `toolResult` whose owning
+ *   assistant appears later is held and pulled forward at the owner.
+ * - A final safety-net pass appends any never-emitted result, guaranteeing no
+ *   `toolResult` is ever lost regardless of input malformation.
+ *
+ * Returns the SAME array reference when already well-formed (no reordering
+ * needed), so callers can cheaply detect a no-op. Otherwise returns a new,
+ * reordered array. Pure: never mutates the input array or its elements.
+ */
+export function repairToolResultOrdering<T extends AgentMessageLike>(messages: T[]): T[] {
+	if (!Array.isArray(messages) || messages.length < 3) return messages;
+
+	// Collect ALL toolResult messages per toolCallId, preserving original order.
+	// A queue (array) rather than last-wins so duplicate results for the same id
+	// are never dropped (Sage #621 review: last-wins could silently lose data).
+	const resultsById = new Map<string, T[]>();
+	for (const m of messages) {
+		if (m && m.role === "toolResult" && typeof m.toolCallId === "string") {
+			const list = resultsById.get(m.toolCallId);
+			if (list) list.push(m);
+			else resultsById.set(m.toolCallId, [m]);
+		}
+	}
+	if (resultsById.size === 0) return messages;
+
+	// First-occurrence index of the assistant that owns each toolCallId. Lets us
+	// HOLD an in-place toolResult whose owning assistant appears LATER, repairing
+	// the result-before-assistant shape (Sage #621 review) instead of emitting it
+	// in a position that would still be invalid.
+	const ownerIndexById = new Map<string, number>();
+	for (let i = 0; i < messages.length; i++) {
+		for (const id of toolUseIds(messages[i])) {
+			if (!ownerIndexById.has(id)) ownerIndexById.set(id, i);
+		}
+	}
+
+	const out: T[] = [];
+	// Track emitted results by message IDENTITY, not by id, so duplicate result
+	// messages sharing a toolCallId are each accounted for individually.
+	const emitted = new Set<T>();
+
+	for (let i = 0; i < messages.length; i++) {
+		const m = messages[i];
+		if (m && m.role === "toolResult" && typeof m.toolCallId === "string") {
+			if (emitted.has(m)) continue; // already pulled forward next to its assistant
+			const owner = ownerIndexById.get(m.toolCallId);
+			// Owner appears later → hold; it will be pulled forward at the owner.
+			// Owner earlier (normal splice case) or orphan (no owner) → emit in place.
+			if (owner !== undefined && owner > i) continue;
+			out.push(m);
+			emitted.add(m);
+			continue;
+		}
+
+		out.push(m);
+
+		// Pull every matching toolResult (all of them, in original order) to
+		// immediately follow this assistant, in tool-call order.
+		for (const id of toolUseIds(m)) {
+			const list = resultsById.get(id);
+			if (!list) continue; // genuinely unanswered tool_use — not repairable here
+			for (const result of list) {
+				if (emitted.has(result)) continue;
+				out.push(result);
+				emitted.add(result);
+			}
+		}
+	}
+
+	// Safety net: guarantee no toolResult is ever dropped. Any result not emitted
+	// above (only reachable via a held-but-never-pulled edge case) is appended in
+	// original order. Guarded by identity so it can never double-emit.
+	for (const m of messages) {
+		if (m && m.role === "toolResult" && typeof m.toolCallId === "string" && !emitted.has(m)) {
+			out.push(m);
+			emitted.add(m);
+		}
+	}
+
+	// Return the original reference when nothing moved (cheap no-op detection).
+	if (out.length === messages.length) {
+		let identical = true;
+		for (let i = 0; i < out.length; i++) {
+			if (out[i] !== messages[i]) {
+				identical = false;
+				break;
+			}
+		}
+		if (identical) return messages;
+	}
+	return out;
+}

package/extensions/taskplane/extension.ts

@@ -107,6 +107,7 @@ import {
 	activateSupervisor,
 	deactivateSupervisor,
 	transitionToRoutingMode,
+	stopBatchMonitoring,
 	freshSupervisorState,
 	registerSupervisorPromptHook,
 	checkSupervisorLockOnStartup,
@@ -118,6 +119,8 @@ import {
 	presentBatchSummary,
 	resolveModelFromString,
 } from "./supervisor.ts";
+import { SupervisorNoticeGate } from "./supervisor-dispatch.ts";
+import { repairToolResultOrdering } from "./context-repair.ts";
 import type {
 	SupervisorConfig,
 	SupervisorRoutingContext,
@@ -1834,6 +1837,123 @@ export default function (pi: ExtensionAPI) {
 	let supervisorState = freshSupervisorState();
 	let supervisorConfig: SupervisorConfig = { ...DEFAULT_SUPERVISOR_CONFIG };
 
+	// ── #621: Batch-end epilogue gate ────────────────────────────────
+	// The batch-end epilogue appends display banners via
+	// pi.sendMessage(..., {triggerTurn:false}), which immediately splices a
+	// custom entry into the session tree. If the interactive agent has a tool
+	// call in flight, that splice lands between an assistant `tool_use` and its
+	// `tool_result` and produces an Anthropic 400 that wedges the session. The
+	// gate runs the epilogue immediately when idle, else defers it to the next
+	// `agent_settled` boundary. `batchGeneration` tags deferred work so a newer
+	// batch invalidates a stale pending epilogue.
+	const noticeGate = new SupervisorNoticeGate();
+	let batchGeneration = 0;
+
+	// #621: Both /orch (doOrchStart) and /orch-resume (doOrchResume) must, on
+	// (re)start, supersede any batch-end epilogue still deferred from a previous
+	// batch: bump the generation (so a later agent_settled no longer matches the
+	// stale pending work) AND drop the pending closure. Extracted into one helper
+	// so the two entry points cannot drift apart again (the original /orch-resume
+	// gap was exactly this drift). Call immediately after freshOrchBatchState().
+	function supersedeDeferredEpilogue(): void {
+		batchGeneration++;
+		noticeGate.invalidate();
+	}
+
+	// #621: The batch-end epilogue, shared by /orch (doOrchStart) and
+	// /orch-resume (doOrchResume). Appends the batch-summary / integration-skipped
+	// banners and transitions the supervisor to routing mode. Both entry points
+	// historically inlined identical logic differing only in `repoRoot` vs
+	// `execCtx!.repoRoot` — the same value, since doOrchStart destructures
+	// `const { repoRoot } = execCtx`. Deferring the WHOLE epilogue (rather than
+	// individual sends) also protects the completed->triggerSupervisorIntegration
+	// branch, whose progress/result messages are the same splice hazard.
+	function runSupervisorBatchEndEpilogue(): void {
+		const mode = orchConfig.orchestrator.integration;
+		const opId = resolveOperatorId(orchConfig);
+		const sDeps: SummaryDeps = {
+			opId,
+			diagnostics: orchBatchState.diagnostics ?? null,
+			mergeResults: (orchBatchState.mergeResults || []).map((mr) => ({
+				waveIndex: mr.waveIndex,
+				status: mr.status,
+				failedLane: mr.failedLane,
+				failureReason: mr.failureReason,
+			})),
+		};
+		if (orchBatchState.phase === "completed" && (mode === "supervised" || mode === "auto")) {
+			triggerSupervisorIntegration(
+				pi,
+				supervisorState,
+				orchBatchState,
+				mode,
+				execCtx!.repoRoot,
+				buildIntegrationExecutor(execCtx!.repoRoot, opId, execCtx!.workspaceRoot),
+				buildCiDeps(execCtx!.repoRoot, execCtx!.workspaceRoot),
+				sDeps,
+			);
+			return;
+		}
+		if ((mode === "supervised" || mode === "auto") && orchBatchState.phase !== "completed") {
+			pi.sendMessage(
+				{
+					customType: "supervisor-integration-skipped",
+					content: [
+						{
+							type: "text",
+							text:
+								`📋 **Batch ended** (phase: ${orchBatchState.phase}). ` +
+								`Integration skipped — only completed batches are eligible.\n` +
+								`Use \`/orch-resume\` to continue or \`/orch-integrate\` manually after resolving issues.`,
+						},
+					],
+					display: `Integration skipped — batch ${orchBatchState.phase}`,
+				},
+				{ triggerTurn: false },
+			);
+		}
+		presentBatchSummary(
+			pi,
+			orchBatchState,
+			execCtx!.workspaceRoot,
+			opId,
+			orchBatchState.diagnostics,
+			sDeps.mergeResults,
+		);
+		const postBatchContext: SupervisorRoutingContext =
+			orchBatchState.phase === "completed"
+				? {
+						routingState: "completed-batch",
+						contextMessage:
+							`Batch **${orchBatchState.batchId}** completed — ` +
+							`${orchBatchState.succeededTasks}/${orchBatchState.totalTasks} tasks succeeded.\n\n` +
+							`The orch branch \`${orchBatchState.orchBranch}\` is ready to integrate.\n` +
+							`Would you like me to integrate it, or would you prefer to review first?\n\n` +
+							`You can also:\n` +
+							`• Run \`/orch-integrate\` (or \`/orch-integrate --pr\`) to integrate\n` +
+							`• Create new tasks for the next batch\n` +
+							`• Run a health check`,
+					}
+				: {
+						routingState: "no-tasks",
+						contextMessage:
+							`Batch **${orchBatchState.batchId}** ended (${orchBatchState.phase}).\n\n` +
+							`${orchBatchState.succeededTasks} succeeded, ${orchBatchState.failedTasks} failed, ` +
+							`${orchBatchState.skippedTasks} skipped.\n\n` +
+							`What would you like to do next?`,
+					};
+		transitionToRoutingMode(pi, supervisorState, postBatchContext);
+	}
+
+	// #621: Route the batch-end epilogue through the idle gate. When the agent
+	// has a tool call in flight, eagerly stop batch monitoring (so a heartbeat
+	// timer send can't splice either) and defer the epilogue to the next settle.
+	function dispatchBatchEndEpilogue(ctx: ExtensionContext): void {
+		const idle = ctx.isIdle();
+		if (!idle) stopBatchMonitoring(supervisorState);
+		noticeGate.runOrDefer(idle, batchGeneration, runSupervisorBatchEndEpilogue);
+	}
+
 	// TP-187 (#538): Zombie-alert filter state
 	// Lane numbers and agent IDs that have reached a terminal state (no-progress
 	// kill, hard-fail, or supervisor-takeover). Supervisor-alert IPC messages
@@ -2377,6 +2497,10 @@ export default function (pi: ExtensionAPI) {
 		orchBatchState = freshOrchBatchState();
 		latestMonitorState = null;
 
+		// #621: a new batch supersedes any epilogue still deferred from the
+		// previous batch. Bump the generation and drop the stale pending work.
+		supersedeDeferredEpilogue();
+
 		// TP-187 (#538): Clear zombie-alert filter for the new batch.
 		clearTerminationFilter("new_batch_started");
 
@@ -2424,80 +2548,7 @@ export default function (pi: ExtensionAPI) {
 				if (changed) updateOrchWidget();
 			},
 			() => {
-				const mode = orchConfig.orchestrator.integration;
-				const opId = resolveOperatorId(orchConfig);
-				const sDeps: SummaryDeps = {
-					opId,
-					diagnostics: orchBatchState.diagnostics ?? null,
-					mergeResults: (orchBatchState.mergeResults || []).map((mr) => ({
-						waveIndex: mr.waveIndex,
-						status: mr.status,
-						failedLane: mr.failedLane,
-						failureReason: mr.failureReason,
-					})),
-				};
-				if (orchBatchState.phase === "completed" && (mode === "supervised" || mode === "auto")) {
-					triggerSupervisorIntegration(
-						pi,
-						supervisorState,
-						orchBatchState,
-						mode,
-						repoRoot,
-						buildIntegrationExecutor(repoRoot, opId, execCtx!.workspaceRoot),
-						buildCiDeps(repoRoot, execCtx!.workspaceRoot),
-						sDeps,
-					);
-					return;
-				}
-				if ((mode === "supervised" || mode === "auto") && orchBatchState.phase !== "completed") {
-					pi.sendMessage(
-						{
-							customType: "supervisor-integration-skipped",
-							content: [
-								{
-									type: "text",
-									text:
-										`📋 **Batch ended** (phase: ${orchBatchState.phase}). ` +
-										`Integration skipped — only completed batches are eligible.\n` +
-										`Use \`/orch-resume\` to continue or \`/orch-integrate\` manually after resolving issues.`,
-								},
-							],
-							display: `Integration skipped — batch ${orchBatchState.phase}`,
-						},
-						{ triggerTurn: false },
-					);
-				}
-				presentBatchSummary(
-					pi,
-					orchBatchState,
-					execCtx!.workspaceRoot,
-					opId,
-					orchBatchState.diagnostics,
-					sDeps.mergeResults,
-				);
-				const postBatchContext: SupervisorRoutingContext =
-					orchBatchState.phase === "completed"
-						? {
-								routingState: "completed-batch",
-								contextMessage:
-									`Batch **${orchBatchState.batchId}** completed — ` +
-									`${orchBatchState.succeededTasks}/${orchBatchState.totalTasks} tasks succeeded.\n\n` +
-									`The orch branch \`${orchBatchState.orchBranch}\` is ready to integrate.\n` +
-									`Would you like me to integrate it, or would you prefer to review first?\n\n` +
-									`You can also:\n` +
-									`• Run \`/orch-integrate\` (or \`/orch-integrate --pr\`) to integrate\n` +
-									`• Create new tasks for the next batch\n` +
-									`• Run a health check`,
-							}
-						: {
-								routingState: "no-tasks",
-								contextMessage:
-									`Batch **${orchBatchState.batchId}** ended (${orchBatchState.phase}).\n\n` +
-									`${orchBatchState.succeededTasks} succeeded, ${orchBatchState.failedTasks} failed, ` +
-									`${orchBatchState.skippedTasks} skipped.\n\n` +
-									`What would you like to do next?`,
-							};
-				transitionToRoutingMode(pi, supervisorState, postBatchContext);
+				dispatchBatchEndEpilogue(ctx);
 			},
 			// ── TP-076: Supervisor alert handler — injects alerts as user messages ──
 			(alert) => {
@@ -2812,6 +2863,14 @@ export default function (pi: ExtensionAPI) {
 		orchBatchState = freshOrchBatchState();
 		latestMonitorState = null;
 
+		// #621: a resume supersedes any epilogue still deferred from the previous
+		// batch, exactly as doOrchStart does. Without this, an epilogue deferred
+		// mid-tool by the prior batch keeps the same batchGeneration; if the user
+		// resumes before `agent_settled` flushes it, onSettled() sees a matching
+		// generation and fires the stale epilogue against the resumed batch
+		// (wrong/duplicate banner). Shared helper mirrors doOrchStart exactly.
+		supersedeDeferredEpilogue();
+
 		// TP-187 (#538): Clear zombie-alert filter so post-resume alerts pass through.
 		clearTerminationFilter("orch_resume_called");
 
@@ -2844,80 +2903,7 @@ export default function (pi: ExtensionAPI) {
 				updateOrchWidget();
 			},
 			() => {
-				const mode = orchConfig.orchestrator.integration;
-				const opId = resolveOperatorId(orchConfig);
-				const sDeps: SummaryDeps = {
-					opId,
-					diagnostics: orchBatchState.diagnostics ?? null,
-					mergeResults: (orchBatchState.mergeResults || []).map((mr) => ({
-						waveIndex: mr.waveIndex,
-						status: mr.status,
-						failedLane: mr.failedLane,
-						failureReason: mr.failureReason,
-					})),
-				};
-				if (orchBatchState.phase === "completed" && (mode === "supervised" || mode === "auto")) {
-					triggerSupervisorIntegration(
-						pi,
-						supervisorState,
-						orchBatchState,
-						mode,
-						execCtx!.repoRoot,
-						buildIntegrationExecutor(execCtx!.repoRoot, opId, execCtx!.workspaceRoot),
-						buildCiDeps(execCtx!.repoRoot, execCtx!.workspaceRoot),
-						sDeps,
-					);
-					return;
-				}
-				if ((mode === "supervised" || mode === "auto") && orchBatchState.phase !== "completed") {
-					pi.sendMessage(
-						{
-							customType: "supervisor-integration-skipped",
-							content: [
-								{
-									type: "text",
-									text:
-										`📋 **Batch ended** (phase: ${orchBatchState.phase}). ` +
-										`Integration skipped — only completed batches are eligible.\n` +
-										`Use \`/orch-resume\` to continue or \`/orch-integrate\` manually after resolving issues.`,
-								},
-							],
-							display: `Integration skipped — batch ${orchBatchState.phase}`,
-						},
-						{ triggerTurn: false },
-					);
-				}
-				presentBatchSummary(
-					pi,
-					orchBatchState,
-					execCtx!.workspaceRoot,
-					opId,
-					orchBatchState.diagnostics,
-					sDeps.mergeResults,
-				);
-				const postBatchContext: SupervisorRoutingContext =
-					orchBatchState.phase === "completed"
-						? {
-								routingState: "completed-batch",
-								contextMessage:
-									`Batch **${orchBatchState.batchId}** completed — ` +
-									`${orchBatchState.succeededTasks}/${orchBatchState.totalTasks} tasks succeeded.\n\n` +
-									`The orch branch \`${orchBatchState.orchBranch}\` is ready to integrate.\n` +
-									`Would you like me to integrate it, or would you prefer to review first?\n\n` +
-									`You can also:\n` +
-									`• Run \`/orch-integrate\` (or \`/orch-integrate --pr\`) to integrate\n` +
-									`• Create new tasks for the next batch\n` +
-									`• Run a health check`,
-							}
-						: {
-								routingState: "no-tasks",
-								contextMessage:
-									`Batch **${orchBatchState.batchId}** ended (${orchBatchState.phase}).\n\n` +
-									`${orchBatchState.succeededTasks} succeeded, ${orchBatchState.failedTasks} failed, ` +
-									`${orchBatchState.skippedTasks} skipped.\n\n` +
-									`What would you like to do next?`,
-							};
-				transitionToRoutingMode(pi, supervisorState, postBatchContext);
+				dispatchBatchEndEpilogue(ctx);
 			},
 			// ── TP-076: Supervisor alert handler — injects alerts as user messages ──
 			(alert) => {
@@ -5611,6 +5597,33 @@ export default function (pi: ExtensionAPI) {
 
 	// ── Session Lifecycle ────────────────────────────────────────────
 
+	// #621 (defense in depth): repair tool_use/tool_result ordering on every
+	// outgoing request. The `context` event fires before each provider call on
+	// the pi-internal AgentMessage[] (before convertToLlm). Any supervisor
+	// `custom` message that was spliced between an assistant tool_use and its
+	// tool_result (from ANY send site — batch summary, integration progress/
+	// result, heartbeat, routing) is moved back after the tool-result group, so
+	// the request is always valid and a mistimed injection can never wedge the
+	// session. Only transforms the per-request context; the persisted tree is
+	// untouched (self-correcting across reloads).
+	pi.on("context", (event: { messages: unknown[] }) => {
+		const repaired = repairToolResultOrdering(event.messages as Array<Record<string, unknown>>);
+		if (repaired !== event.messages) return { messages: repaired };
+	});
+
+	// #621: Flush a deferred batch-end epilogue once the interactive agent has
+	// fully settled (all tool_results appended). Re-check idleness here because a
+	// prior settle handler may have started another run.
+	pi.on("agent_settled", (_event: unknown, ctx: ExtensionContext) => {
+		noticeGate.onSettled(ctx.isIdle(), batchGeneration);
+	});
+
+	// #621: Drop any deferred epilogue and disable the gate on shutdown so a
+	// stale closure cannot fire against a replaced session.
+	pi.on("session_shutdown", () => {
+		noticeGate.dispose();
+	});
+
 	pi.on("session_start", async (_event, ctx) => {
 		// Store widget context for dashboard updates (needed even if startup fails)
 		orchWidgetCtx = ctx;

package/extensions/taskplane/supervisor-dispatch.ts

@@ -0,0 +1,103 @@
+/**
+ * Batch-end epilogue gate — issue #621.
+ *
+ * PROBLEM
+ * -------
+ * The supervisor's batch-end epilogue appends display banners to the session via
+ * `pi.sendMessage(msg, { triggerTurn: false })`. In pi's `sendCustomMessage`,
+ * `{ triggerTurn: false }` always takes the branch that IMMEDIATELY appends a
+ * `custom` entry to the session tree at the current leaf — even while the
+ * interactive agent is streaming. If the agent has a tool call in flight (an
+ * assistant `tool_use` has been appended but its `tool_result` has not yet
+ * landed), that append splices a user-role `custom` message BETWEEN the
+ * `tool_use` and its `tool_result`. On the next request Anthropic rejects the
+ * conversation with a 400 ("`tool_result` ... must have a corresponding
+ * `tool_use` block in the previous message"), permanently wedging the session.
+ *
+ * FIX
+ * ---
+ * Run the epilogue immediately when the agent is idle (the leaf is a terminal
+ * message, so an append is safe and the banner renders now). Otherwise defer it
+ * to the next `agent_settled` boundary — the first lifecycle point at which all
+ * tool results, retries, compaction, and queued continuations have finished, so
+ * an append can no longer split a `tool_use`/`tool_result` pair.
+ *
+ * Notes:
+ * - `deliverAs: "nextTurn"` is NOT usable here: it pushes into the next turn's
+ *   in-memory context only, without persisting the entry or emitting
+ *   message_start/end, so display banners would be silently dropped.
+ * - The gate is session-scoped (constructed inside the extension factory), holds
+ *   only a plain closure + a generation tag (no captured `ctx`), and is
+ *   invalidated by a newer batch or by session shutdown.
+ */
+
+/**
+ * Gates the supervisor batch-end epilogue on interactive-agent idleness so its
+ * display banners can never be appended between a `tool_use` and its
+ * `tool_result` (#621).
+ */
+export class SupervisorNoticeGate {
+	private pending: (() => void) | null = null;
+	private pendingGeneration = -1;
+	private active = true;
+
+	/**
+	 * Run `epilogue` now when `idle`, otherwise defer it to the next settle.
+	 *
+	 * @param idle       Current `ctx.isIdle()` at the batch-end callback.
+	 * @param generation Monotonic batch counter; tags the deferred work so a
+	 *                   newer batch can invalidate a stale pending epilogue.
+	 * @param epilogue   Side-effecting closure that performs the batch-end sends
+	 *                   (integration-skipped banner, batch summary, routing
+	 *                   transition). Must be safe to run at a settle boundary.
+	 */
+	runOrDefer(idle: boolean, generation: number, epilogue: () => void): void {
+		if (!this.active) return;
+		if (idle) {
+			epilogue();
+			return;
+		}
+		// Coalesce: keep only the most recent epilogue for the latest generation.
+		this.pending = epilogue;
+		this.pendingGeneration = generation;
+	}
+
+	/**
+	 * Flush a deferred epilogue at an `agent_settled` boundary.
+	 *
+	 * Re-checks idleness (another extension may have started a run from its own
+	 * settle handler) and the generation (a newer batch supersedes it).
+	 */
+	onSettled(idle: boolean, generation: number): void {
+		if (!this.active) return;
+		if (!this.pending) return;
+		if (!idle) return;
+		if (this.pendingGeneration !== generation) {
+			// A newer batch superseded this epilogue — drop it.
+			this.pending = null;
+			this.pendingGeneration = -1;
+			return;
+		}
+		const epilogue = this.pending;
+		this.pending = null;
+		this.pendingGeneration = -1;
+		epilogue();
+	}
+
+	/** Drop any deferred epilogue (a newer batch supersedes it). */
+	invalidate(): void {
+		this.pending = null;
+		this.pendingGeneration = -1;
+	}
+
+	/** Permanently disable the gate and drop pending work (session shutdown). */
+	dispose(): void {
+		this.active = false;
+		this.invalidate();
+	}
+
+	/** Test/inspection helper: whether an epilogue is currently deferred. */
+	hasPending(): boolean {
+		return this.pending !== null;
+	}
+}

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);
 
@@ -3174,13 +3200,18 @@ export async function deactivateSupervisor(
  *
  * @since TP-128
  */
-export async function transitionToRoutingMode(
-	pi: ExtensionAPI,
-	state: SupervisorState,
-	routingContext: SupervisorRoutingContext,
-): Promise<void> {
-	if (!state.active) return;
-
+/**
+ * Tear down batch-monitoring infrastructure (event tailer, heartbeat timer,
+ * lockfile). Idempotent — safe to call multiple times.
+ *
+ * Extracted from `transitionToRoutingMode` (#621) so the batch-end epilogue can
+ * stop background timers EAGERLY when it must defer its display banners past an
+ * in-flight tool call. Stopping the heartbeat immediately prevents a
+ * timer-origin `pi.sendMessage(..., {triggerTurn:false})` from splicing a custom
+ * entry between an assistant `tool_use` and its `tool_result` during the defer
+ * window.
+ */
+export function stopBatchMonitoring(state: SupervisorState): void {
 	// Tear down batch-monitoring infrastructure
 	stopEventTailer(state.eventTailer);
 
@@ -3197,6 +3228,16 @@ export async function transitionToRoutingMode(
 		}
 	}
 	state.lockSessionId = "";
+}
+
+export async function transitionToRoutingMode(
+	pi: ExtensionAPI,
+	state: SupervisorState,
+	routingContext: SupervisorRoutingContext,
+): Promise<void> {
+	if (!state.active) return;
+
+	stopBatchMonitoring(state);
 
 	// Present deferred batch summary if any
 	if (state.pendingSummaryDeps && state.batchStateRef && state.stateRoot) {
@@ -3710,6 +3751,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 +3853,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 +4571,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 +4584,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.3",
+  "version": "0.30.5",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",