taskplane 0.30.4 → 0.30.6

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

@@ -23,13 +23,22 @@
 
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "@mariozechner/pi-ai";
-import { writeFileSync, readFileSync, existsSync, mkdirSync, renameSync, unlinkSync } from "fs";
+import {
+	writeFileSync,
+	readFileSync,
+	readdirSync,
+	existsSync,
+	mkdirSync,
+	renameSync,
+	unlinkSync,
+} from "fs";
 import { join, dirname } from "path";
 import { spawn as nodeSpawn } from "child_process";
 import { resolvePiCliPath, resolveTaskplaneAgentTemplate } from "./path-resolver.ts";
 import { loadPiSettingsPackages, filterExcludedExtensions } from "./settings-loader.ts";
 import { randomBytes } from "crypto";
 import { buildExpansionRequestId, type SegmentExpansionRequest } from "./types.ts";
+import { latestReviewFilesPerGate, parseReviewVerdict } from "./review-analysis.ts";
 
 /**
  * Resolve the outbox directory from environment variables.
@@ -174,6 +183,28 @@ function writeSegmentExpansionRequest(request: SegmentExpansionRequest): string
  * @param stepNum the step number being reviewed
  * @returns true iff the step is marked Complete in STATUS.md
  */
+/**
+ * #629: does the LATEST review file for `{type}-step{N}` read REVISE/RETHINK?
+ * Used to exempt a remediation re-review from the TP-186 complete-step guard.
+ * Fail-closed: unreadable dir/file → false (guard stays in force).
+ */
+export function hasOutstandingNonApproveReview(
+	reviewsDir: string,
+	reviewType: string,
+	stepNum: number,
+): boolean {
+	try {
+		if (!existsSync(reviewsDir)) return false;
+		const latest = latestReviewFilesPerGate(readdirSync(reviewsDir));
+		const filename = latest.get(`${reviewType.toLowerCase()}-step${stepNum}`);
+		if (!filename) return false;
+		const verdict = parseReviewVerdict(readFileSync(join(reviewsDir, filename), "utf-8"));
+		return verdict === "REVISE" || verdict === "RETHINK";
+	} catch {
+		return false;
+	}
+}
+
 export function isStepMarkedComplete(statusPath: string, stepNum: number): boolean {
 	let content: string;
 	try {
@@ -822,7 +853,18 @@ export default function (pi: ExtensionAPI) {
 			// violated the Order of Operations contract; the only safe path
 			// is to revert STATUS first, then re-call review_step. Plan
 			// reviews are exempt because they fire BEFORE implementation.
-			if (reviewType !== "plan" && isStepMarkedComplete(statusPath, stepNum)) {
+			//
+			// #629 exemption: when the step is Complete but the LATEST review for
+			// this gate is REVISE/RETHINK, the runtime's finalize gate has refused
+			// (or will refuse) the task and spawned a remediation iteration whose
+			// whole purpose is to re-run this review. That state IS the anomaly
+			// being repaired — a re-review is the correct action, not an order
+			// violation. Refusing here would make the documented remedy unreachable.
+			if (
+				reviewType !== "plan" &&
+				isStepMarkedComplete(statusPath, stepNum) &&
+				!hasOutstandingNonApproveReview(reviewsDir, reviewType, stepNum)
+			) {
 				const taskIdMatch = statusPath.match(/[\\/]([A-Z]{2,}-\d+)[^\\/]*[\\/]STATUS\.md$/);
 				const taskId = taskIdMatch ? taskIdMatch[1] : "<TASK-ID>";
 				const refusal = [
@@ -944,13 +986,23 @@ export default function (pi: ExtensionAPI) {
 				// Read review output and extract verdict
 				if (existsSync(outputPath)) {
 					const reviewContent = readFileSync(outputPath, "utf-8");
-					const verdictMatch = reviewContent.match(/###?\s*Verdict[:\s]*(APPROVE|REVISE|RETHINK)/i);
-					let verdict = verdictMatch ? verdictMatch[1].toUpperCase() : "UNKNOWN";
+					// #624 (severity upgrade): robust, FAIL-CLOSED verdict extraction. The
+					// old regex ('###?\s*Verdict[:\s]*…') missed common reviewer format
+					// variants, and its fallback checked the substring "approve" FIRST — so
+					// a REVISE review whose body merely contained "approve" (e.g. "cannot
+					// approve") was returned to the worker as APPROVE. Workers then marked
+					// steps complete and advanced past unaddressed findings. The review
+					// gate must NEVER fail open: APPROVE is only ever taken from an
+					// explicit Verdict line (parseReviewVerdict handles heading/bold/plain/
+					// dash/bracket variants and skips the template placeholder). The body
+					// fallback below may only produce fail-closed guesses (REVISE/RETHINK).
+					const parsedVerdict = parseReviewVerdict(reviewContent);
+					let verdict: string = parsedVerdict ?? "UNKNOWN";
 					if (verdict === "UNKNOWN") {
 						const lower = reviewContent.toLowerCase();
-						if (lower.includes("approve") && !lower.includes("do not approve")) verdict = "APPROVE";
-						else if (lower.includes("revise") || lower.includes("changes requested")) verdict = "REVISE";
-						else if (lower.includes("rethink")) verdict = "RETHINK";
+						if (/\brevise\b/.test(lower) || lower.includes("changes requested")) verdict = "REVISE";
+						else if (/\brethink\b/.test(lower)) verdict = "RETHINK";
+						// NO approve fallback — an approval must be explicit.
 					}
 
 					// Log review in STATUS.md execution log
@@ -986,7 +1038,13 @@ export default function (pi: ExtensionAPI) {
 					} else {
 						return {
 							content: [
-								{ type: "text" as const, text: `Review complete (verdict unclear). See ${reviewFile}` },
+								{
+									type: "text" as const,
+									text:
+										`Review complete (verdict unclear). Read ${reviewFile} and follow its ` +
+										`Verdict line — do NOT treat this as an approval or mark the step complete ` +
+										`without an explicit APPROVE.`,
+								},
 							],
 							details: undefined,
 						};

package/extensions/taskplane/agent-host.ts

@@ -40,6 +40,7 @@ import type {
 	RuntimeAgentEventType,
 	RuntimeAgentManifest,
 	PacketPaths,
+	ReviewDisposition,
 } from "./types.ts";
 
 import {
@@ -144,6 +145,65 @@ export function buildWorkerToolsAllowlist(userTools: string | undefined | null):
 	return Array.from(merged).join(",");
 }
 
+/**
+ * Normalize the freeform text a `review_step` tool call returns into a
+ * {@link ReviewDisposition}. The tool returns clean leading tokens
+ * (`APPROVE`, `REVISE: …`, `RETHINK — …`, `UNAVAILABLE — …`, `REFUSED: …`),
+ * but this parser is defensive: it matches a leading verdict token
+ * case-insensitively and falls back to a substring scan, returning `UNKNOWN`
+ * when nothing recognizable is present.
+ *
+ * Pure and side-effect-free so it can be unit-tested directly.
+ *
+ * @since review-boundary notifications
+ */
+/**
+ * Extract the review file path from a review_step tool return. The tool appends
+ * "Full review: .reviews/R{NNN}-{type}-step{N}.md" (REVISE) or
+ * "See .reviews/R{NNN}-{type}-step{N}.md" (RETHINK). Returns undefined when no
+ * such reference is present (e.g. APPROVE returns just "APPROVE").
+ */
+export function extractReviewPath(resultText: string | undefined | null): string | undefined {
+	if (!resultText || typeof resultText !== "string") return undefined;
+	const m = resultText.match(/(?:Full review:|See)\s+(\S*R\d+-[a-z]+-step\d+\.md)\b/i);
+	if (m) return m[1];
+	const m2 = resultText.match(/(\S*R\d+-[a-z]+-step\d+\.md)\b/i);
+	return m2 ? m2[1] : undefined;
+}
+
+export function normalizeReviewDisposition(
+	resultText: string | undefined | null,
+): ReviewDisposition {
+	if (!resultText || typeof resultText !== "string") return "UNKNOWN";
+	const text = resultText.trim();
+	if (text.length === 0) return "UNKNOWN";
+	// Leading-token match (the tool's canonical output shape).
+	const lead = text.toUpperCase();
+	if (/^APPROVE\b/.test(lead)) return "APPROVE";
+	if (/^REVISE\b/.test(lead)) return "REVISE";
+	if (/^RETHINK\b/.test(lead)) return "RETHINK";
+	if (/^REFUSED\b/.test(lead)) return "REFUSED";
+	if (/^UNAVAILABLE\b/.test(lead)) return "UNAVAILABLE";
+	// Defensive fallback: scan for the token anywhere, most-specific first, using
+	// word boundaries so substrings inside other words don't false-match.
+	// REFUSED and UNAVAILABLE are checked before REVISE/RETHINK because their
+	// bodies may quote a verdict word.
+	if (/\bREFUSED\b/.test(lead)) return "REFUSED";
+	if (/\bUNAVAILABLE\b/.test(lead)) return "UNAVAILABLE";
+	if (/\bRETHINK\b/.test(lead)) return "RETHINK";
+	if (/\bREVISE\b/.test(lead) || /\bCHANGES REQUESTED\b/.test(lead)) return "REVISE";
+	// Approve only on a clean, non-negated APPROVE token. Reject explicit
+	// negations ("do not approve", "not approved", "disapprove", "unapproved").
+	if (
+		/\bAPPROVE\b/.test(lead) &&
+		!/\bDO NOT APPROVE\b/.test(lead) &&
+		!/\bNOT APPROVE\b/.test(lead)
+	) {
+		return "APPROVE";
+	}
+	return "UNKNOWN";
+}
+
 // ── Conversation Payload Helpers (TP-111) ───────────────────────────────
 
 /** Maximum characters for conversation event text payloads. */
@@ -181,6 +241,37 @@ function extractAssistantText(message: Record<string, unknown>): string {
 	return "";
 }
 
+/**
+ * Extract text from a Pi RPC `tool_execution_end` result, which — like message
+ * content — may be a plain string, an array of `{type:"text",text}` blocks, or
+ * an object with a `content` field (the shape tool handlers return). The old
+ * `typeof event.result === "string" ? ... : String(event.output)` extraction
+ * silently produced an empty/garbage string for structured results, which made
+ * review_step verdicts unparseable and mis-fired "Reviewer unavailable" (#624).
+ */
+export function extractToolResultText(event: { result?: unknown; output?: unknown }): string {
+	const fromValue = (val: unknown): string | null => {
+		if (typeof val === "string") return val;
+		if (Array.isArray(val)) {
+			const texts = val
+				.filter(
+					(b: unknown): b is { type: string; text: string } =>
+						typeof b === "object" &&
+						b !== null &&
+						(b as { type?: unknown }).type === "text" &&
+						typeof (b as { text?: unknown }).text === "string",
+				)
+				.map((b) => b.text);
+			if (texts.length > 0) return texts.join("\n");
+		}
+		if (val && typeof val === "object" && "content" in val) {
+			return extractAssistantText(val as Record<string, unknown>);
+		}
+		return null;
+	};
+	return fromValue(event.result) ?? fromValue(event.output) ?? "";
+}
+
 // ── Types ────────────────────────────────────────────────────────────
 
 /**
@@ -250,6 +341,11 @@ export interface AgentHostOptions {
 	 * @since TP-172
 	 */
 	maxExitInterceptions?: number;
+	/**
+	 * Upper bound (ms) for one onPrematureExit intercept before the host stops
+	 * waiting. Must exceed the lane's supervisor-reply window; default 120s.
+	 */
+	exitInterceptSafetyMs?: number;
 }
 
 /**
@@ -396,6 +492,14 @@ export function spawnAgent(
 	let lastTool = "",
 		error: string | null = null;
 	let contextUsage: AgentHostResult["contextUsage"] = null;
+	/**
+	 * In-flight review_step boundary state (review-boundary notifications). Set at
+	 * tool_execution_start so the end event and any crash-abort can carry the
+	 * step/reviewType identity (tool_execution_end does not include the original
+	 * args). review_step calls are sequential within a worker (the worker blocks
+	 * on the verdict), so a single pending slot is sufficient.
+	 */
+	let pendingReview: { step?: number; reviewType?: string } | null = null;
 	let stderrBuffer = "";
 	const STDERR_MAX = 2048;
 	/** Last assistant message text captured from message_end events (TP-172) */
@@ -589,7 +693,10 @@ export function spawnAgent(
 						try {
 							appendFileSync(
 								opts.steeringPendingPath,
-								JSON.stringify({ ts: msg.timestamp, content: msg.content, id: msg.id }) + "\n",
+								// #630: `type` lets the lane-runner tell an acknowledgement (info)
+								// from a ruling/instruction (steer) for hold bookkeeping.
+								JSON.stringify({ ts: msg.timestamp, content: msg.content, id: msg.id, type: msg.type }) +
+									"\n",
 								"utf-8",
 							);
 						} catch {
@@ -671,6 +778,19 @@ export function spawnAgent(
 					: exitCode === 0 && agentEnded
 						? "agent_exited"
 						: "agent_crashed";
+			// Review-boundary: if the worker died mid-review, close the dangling
+			// review_started so the supervisor doesn't see an orphaned "review
+			// starting" with no end. Emitted as review_failed (aborted) before the
+			// terminal exit event.
+			if (pendingReview) {
+				emitEvent("review_failed", {
+					step: pendingReview.step,
+					reviewType: pendingReview.reviewType,
+					disposition: "UNKNOWN",
+					summary: `review aborted (${exitEventType})`,
+				});
+				pendingReview = null;
+			}
 			emitEvent(exitEventType, { exitCode, signal, durationMs: result.durationMs, timedOut });
 
 			// Registry integration: update manifest to terminal status
@@ -781,17 +901,58 @@ export function spawnAgent(
 						// TP-111: Bounded payload only — no raw args in durable event log
 						const toolPath = event.args?.path ? String(event.args.path).slice(0, 200) : "";
 						emitEvent("tool_call", { tool: toolName, path: toolPath, argsPreview: argPreview });
+						// Review-boundary notification: the review START. review_step spawns a
+						// reviewer; surfacing this lets the supervisor track review activity
+						// live (see lane-runner onEvent bridge + supervisor tailer).
+						if (toolName === "review_step") {
+							const reviewStep =
+								event.args && typeof event.args === "object"
+									? (event.args as { step?: unknown }).step
+									: undefined;
+							const reviewType =
+								event.args && typeof event.args === "object"
+									? (event.args as { type?: unknown }).type
+									: undefined;
+							const stepNum = typeof reviewStep === "number" ? reviewStep : undefined;
+							const rType = typeof reviewType === "string" ? reviewType : undefined;
+							// Remember identity so the end/abort events can carry step+reviewType
+							// (tool_execution_end omits args).
+							pendingReview = { step: stepNum, reviewType: rType };
+							emitEvent("review_requested", { step: stepNum, reviewType: rType });
+						}
 						break;
 					}
 					case "tool_execution_end": {
-						// TP-111: Include bounded result summary for dashboard display
-						const toolResultSummary =
-							typeof event.result === "string"
-								? event.result.slice(0, 200)
-								: event.output
-									? String(event.output).slice(0, 200)
-									: "";
+						// #624: extract robustly — tool results are often structured content
+						// arrays, not plain strings; the old extraction produced "" for those.
+						const fullResult = extractToolResultText(event);
+						const toolResultSummary = fullResult.slice(0, 200);
 						emitEvent("tool_result", { tool: event.toolName, summary: toolResultSummary });
+						// Review-boundary notification: the review END. Normalize the reviewer
+						// verdict and emit review_completed (APPROVE/REVISE/RETHINK/REFUSED) or
+						// review_failed. Only a GENUINE UNAVAILABLE (reviewer subprocess failed
+						// / produced no output) is the "broken reviewer" signal. A parse miss
+						// (UNKNOWN) must NOT masquerade as a broken reviewer (#624) — emit it as
+						// review_completed; lane-runner authoritatively resolves the verdict from
+						// the review file on disk.
+						if (event.toolName === "review_step") {
+							const disposition = normalizeReviewDisposition(fullResult);
+							const reviewFields = {
+								step: pendingReview?.step,
+								reviewType: pendingReview?.reviewType,
+								disposition,
+								summary: toolResultSummary,
+								// review_step embeds the review file path in its REVISE/RETHINK
+								// return; surfacing it lets lane-runner read the EXACT review file.
+								reviewPath: extractReviewPath(fullResult),
+							};
+							if (disposition === "UNAVAILABLE") {
+								emitEvent("review_failed", reviewFields);
+							} else {
+								emitEvent("review_completed", reviewFields);
+							}
+							pendingReview = null;
+						}
 						break;
 					}
 					case "auto_retry_start": {
@@ -841,7 +1002,7 @@ export function spawnAgent(
 						const shouldIntercept = opts.onPrematureExit && exitInterceptionCount < maxExitInterceptions;
 						if (shouldIntercept) {
 							exitInterceptionCount++;
-							const INTERCEPTION_TIMEOUT_MS = 120_000; // 2 minute safety timeout
+							const INTERCEPTION_TIMEOUT_MS = opts.exitInterceptSafetyMs ?? 120_000; // safety timeout (> lane window)
 							// Wrap in Promise.resolve().then() to catch synchronous throws
 							const interceptPromise = Promise.resolve().then(() =>
 								opts.onPrematureExit!(lastAssistantMessage),

package/extensions/taskplane/config-loader.ts

@@ -1268,6 +1268,9 @@ export function toTaskRunnerConfig(config: TaskplaneConfig): import("./types.ts"
 			thinking: config.taskRunner.worker.thinking,
 			tools: config.taskRunner.worker.tools,
 			excludeExtensions: [...(config.taskRunner.worker.excludeExtensions ?? [])],
+			...(typeof config.taskRunner.worker.exitInterceptTimeoutSec === "number"
+				? { exitInterceptTimeoutSec: config.taskRunner.worker.exitInterceptTimeoutSec }
+				: {}),
 		},
 		model_fallback: config.taskRunner.modelFallback ?? "inherit",
 		reviewer: {
@@ -1275,6 +1278,12 @@ export function toTaskRunnerConfig(config: TaskplaneConfig): import("./types.ts"
 			thinking: config.taskRunner.reviewer.thinking,
 			tools: config.taskRunner.reviewer.tools,
 			excludeExtensions: [...(config.taskRunner.reviewer.excludeExtensions ?? [])],
+			...(config.taskRunner.reviewer.severityLabels
+				? { severityLabels: [...config.taskRunner.reviewer.severityLabels] }
+				: {}),
+			...(config.taskRunner.reviewer.spiral
+				? { spiral: { ...config.taskRunner.reviewer.spiral } }
+				: {}),
 		},
 		workerExcludeExtensions: [...(config.taskRunner.worker.excludeExtensions ?? [])],
 	};

package/extensions/taskplane/config-schema.ts

@@ -118,9 +118,34 @@ export interface WorkerConfig {
 	spawnMode?: "subprocess";
 	/** Package specifiers to exclude from extension forwarding for worker agents (exact match). @since TP-180 */
 	excludeExtensions?: string[];
+	/**
+	 * How long (seconds) the lane waits for a supervisor reply when it intercepts a
+	 * worker's premature exit, before letting the session close. Default 60. Raise
+	 * it when the supervisor is often inside long tool calls (a blocking
+	 * `--wait` mid-tool-call cannot answer in 60s — penster feedback #3, item 5).
+	 * Bounded to 15..1800.
+	 */
+	exitInterceptTimeoutSec?: number;
 }
 
 /** Reviewer agent configuration */
+/**
+ * Revision-spiral detection tuning (review-boundary supervisor notifications).
+ * When a step is reviewed repeatedly without converging, the supervisor is
+ * escalated so it can adjudicate / steer the worker. Detection is notify-based,
+ * not a hard cap on revisions.
+ */
+export interface ReviewSpiralConfig {
+	/** Master switch for spiral escalation (per-boundary notifications are always on). */
+	enabled: boolean;
+	/** Consecutive non-APPROVE reviews on the SAME step before the first escalation. */
+	threshold: number;
+	/** Minimum further non-APPROVE reviews between re-escalations (anti-spam spacing). */
+	cooldownReviews: number;
+	/** Whether UNAVAILABLE reviews count toward the spiral (default false: broken-reviewer signal, not a spiral). */
+	treatUnavailableAsNonApprove: boolean;
+}
+
 export interface ReviewerConfig {
 	/** Reviewer model (empty = inherit session model) */
 	model: string;
@@ -130,6 +155,15 @@ export interface ReviewerConfig {
 	thinking: string;
 	/** Package specifiers to exclude from extension forwarding for reviewer agents (exact match). @since TP-180 */
 	excludeExtensions?: string[];
+	/**
+	 * Ordered severity vocabulary (highest severity first) used to bucket review
+	 * findings for spiral-vs-converging analysis. Core default is generic
+	 * (critical/important/minor); projects whose reviewer emits a different scheme
+	 * (e.g. P0/P1/P2) override this. Never hardcode a project vocabulary in core.
+	 */
+	severityLabels: string[];
+	/** Revision-spiral detection tuning. */
+	spiral: ReviewSpiralConfig;
 }
 
 /** Context/resource limits for task execution */
@@ -598,7 +632,19 @@ export const DEFAULT_TASK_RUNNER_SECTION: TaskRunnerSection = {
 	// bridge tools are appended at the lane-runner spawn site by
 	// `buildWorkerToolsAllowlist()`, not here.
 	worker: { model: "", tools: DEFAULT_WORKER_USER_TOOLS, thinking: "", excludeExtensions: [] },
-	reviewer: { model: "", tools: "read,bash,grep,find,ls", thinking: "on", excludeExtensions: [] },
+	reviewer: {
+		model: "",
+		tools: "read,bash,grep,find,ls",
+		thinking: "on",
+		excludeExtensions: [],
+		severityLabels: ["critical", "important", "minor"],
+		spiral: {
+			enabled: true,
+			threshold: 3,
+			cooldownReviews: 2,
+			treatUnavailableAsNonApprove: false,
+		},
+	},
 	context: {
 		workerContextWindow: 0,
 		warnPercent: 85,

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;
+}