@selesai/code 0.13.40 → 0.14.3

package/dist/extensions/pi-subagents/src/runs/shared/parallel-handoff.ts

@@ -1,3 +1,4 @@
+import { withHandoffWriteLock, withRepositoryWorktreeLock } from "./worktree-lock.ts";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
@@ -20,7 +21,7 @@ import type {
 	WorktreeSetupProgress,
 	WorktreeCleanupIntent,
 } from "./worktree.ts";
-import { cleanupWorktrees } from "./worktree.ts";
+import { cleanupWorktrees, withWorktreeTransaction } from "./worktree.ts";
 import { assertWorkflowLaneKey, normalizeWorkflowLaneMetadata } from "./lane-metadata.ts";
 
 export interface ParallelHandoffResult {
@@ -159,6 +160,26 @@ function pathInside(root: string, candidate: string): boolean {
 	return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
 }
 
+export async function protectRetainedWorktreeForResume(manifestPath: string, runId: string, childIndex: number, signal?: AbortSignal): Promise<string> {
+	const original = readParallelHandoffManifest(manifestPath);
+	const group = original?.groups.find((item) => item.children.some((child) => child.index === childIndex));
+	if (!group) throw new Error("Retained worktree handoff disappeared before resume admission.");
+	return withWorktreeTransaction(() => withRepositoryWorktreeLock(group.repoRoot, () => withHandoffWriteLock(manifestPath, () => {
+		signal?.throwIfAborted();
+		const cwd = resolveRetainedWorktreeCwd(manifestPath, runId, childIndex);
+		if (!cwd) throw new Error("Retained worktree ownership disappeared before resume admission.");
+		const manifest = readParallelHandoffManifest(manifestPath)!;
+		const currentGroup = manifest.groups.find((item) => item.children.some((child) => child.index === childIndex))!;
+		const child = currentGroup.children.find((item) => item.index === childIndex)!;
+		const task = currentGroup.cleanup.tasks.find((item) => item.index === child.taskIndex)!;
+		task.preserved = true;
+		task.reason = "retained child resume requires managed worktree cwd";
+		manifest.updatedAt = Date.now();
+		writeAtomicJson(manifestPath, manifest);
+		return cwd;
+	}), { signal }));
+}
+
 export function resolveRetainedWorktreeCwd(manifestPath: string, runId: string, childIndex: number): string | undefined {
 	const manifest = readParallelHandoffManifest(manifestPath);
 	if (!manifest) return undefined;
@@ -434,7 +455,11 @@ export interface ParallelHandoffEvidenceResult {
 	text: string;
 }
 
-export function recordParallelHandoffMerge(input: { manifestPath: string; laneId: string; merge: unknown; now?: number }): ParallelHandoffEvidenceResult {
+export function recordParallelHandoffMerge(...args: Parameters<typeof recordParallelHandoffMergeUnlocked>): ReturnType<typeof recordParallelHandoffMergeUnlocked> {
+	return withHandoffWriteLock(args[0].manifestPath, () => recordParallelHandoffMergeUnlocked(...args));
+}
+
+function recordParallelHandoffMergeUnlocked(input: { manifestPath: string; laneId: string; merge: unknown; now?: number }): ParallelHandoffEvidenceResult {
 	const manifest = readParallelHandoffManifest(input.manifestPath);
 	if (!manifest) throw new Error(`Parallel handoff manifest not found: ${input.manifestPath}`);
 	validateManifestForLaneEvidence(manifest, boundedString(input.laneId, "laneId", MAX_SUPERSESSION_ID_LENGTH));
@@ -452,7 +477,11 @@ export function recordParallelHandoffMerge(input: { manifestPath: string; laneId
 	return { manifest: updated, reference: referenceFor(input.manifestPath, updated), text: formatStoredParallelHandoffCleanup(input.manifestPath, updated) };
 }
 
-export function recordParallelHandoffSupersession(input: { manifestPath: string; laneId: string; supersession: unknown; now?: number }): ParallelHandoffEvidenceResult {
+export function recordParallelHandoffSupersession(...args: Parameters<typeof recordParallelHandoffSupersessionUnlocked>): ReturnType<typeof recordParallelHandoffSupersessionUnlocked> {
+	return withHandoffWriteLock(args[0].manifestPath, () => recordParallelHandoffSupersessionUnlocked(...args));
+}
+
+function recordParallelHandoffSupersessionUnlocked(input: { manifestPath: string; laneId: string; supersession: unknown; now?: number }): ParallelHandoffEvidenceResult {
 	const manifest = readParallelHandoffManifest(input.manifestPath);
 	if (!manifest) throw new Error(`Parallel handoff manifest not found: ${input.manifestPath}`);
 	const laneId = boundedString(input.laneId, "laneId", MAX_SUPERSESSION_ID_LENGTH);
@@ -494,7 +523,11 @@ function missingDiff(input: { manifestPath: string; stepIndex: number; taskIndex
 	};
 }
 
-export function writeParallelHandoffGroup(input: {
+export function writeParallelHandoffGroup(...args: Parameters<typeof writeParallelHandoffGroupUnlocked>): ReturnType<typeof writeParallelHandoffGroupUnlocked> {
+	return withHandoffWriteLock(args[0].manifestPath, () => writeParallelHandoffGroupUnlocked(...args));
+}
+
+function writeParallelHandoffGroupUnlocked(input: {
 	manifestPath: string;
 	runId: string;
 	mode: "single" | "parallel" | "chain";
@@ -577,6 +610,7 @@ export function writeParallelHandoffGroup(input: {
 				branch: worktree.branch,
 				...(worktree.provider ? { provider: worktree.provider } : {}),
 				...(worktree.naming ? { naming: worktree.naming } : {}),
+				...(worktree.recordedBaseDir ? { recordedBaseDir: worktree.recordedBaseDir } : {}),
 				worktreeRemoved: false,
 				branchRemoved: false,
 				preserved: true,
@@ -584,6 +618,15 @@ export function writeParallelHandoffGroup(input: {
 			})),
 		},
 	};
+	for (const task of group.cleanup.tasks) {
+		const previous = existing?.groups.flatMap((item) => item.cleanup.tasks).find((item) => item.path === task.path && item.branch === task.branch);
+		if (previous?.worktreeRemoved) task.worktreeRemoved = true;
+		if (previous?.branchRemoved) task.branchRemoved = true;
+		if (!task.worktreeRemoved && previous?.reason?.includes("retained child resume")) {
+			task.preserved = true;
+			task.reason = previous.reason;
+		}
+	}
 	const groups = existing?.groups.filter((candidate) => candidate.stepIndex !== input.stepIndex) ?? [];
 	groups.push(group);
 	groups.sort((left, right) => left.stepIndex - right.stepIndex);
@@ -664,7 +707,7 @@ export function writeWorktreeSetupHandoff(input: Omit<Parameters<typeof writePar
 				const task = cleanup?.tasks.find((candidate) => candidate.index === worktree.index);
 				return task ? { ...task, reason: task.reason && diagnostic(task.reason), errors: task.errors?.map(diagnostic) } : {
 					index: worktree.index, path: worktree.path, branch: worktree.branch,
-					provider: worktree.provider, naming: worktree.naming,
+					provider: worktree.provider, naming: worktree.naming, recordedBaseDir: worktree.recordedBaseDir,
 					worktreeRemoved: false, branchRemoved: false, preserved: true,
 					reason: "setup pending durable handoff capture",
 				};
@@ -681,7 +724,11 @@ export function formatParallelHandoffError(error: unknown): string {
 	return `Worktree handoff unavailable: ${error instanceof Error ? error.message : String(error)}`;
 }
 
-export function discardPreservedWorktrees(
+export function discardPreservedWorktrees(...args: Parameters<typeof discardPreservedWorktreesUnlocked>): ReturnType<typeof discardPreservedWorktreesUnlocked> {
+	return withHandoffWriteLock(args[0], () => discardPreservedWorktreesUnlocked(...args));
+}
+
+function discardPreservedWorktreesUnlocked(
 	manifestPath: string,
 	authorization: Extract<WorktreeCleanupIntent, { kind: "discard" }>["authorization"],
 ): { manifest: ParallelHandoffManifest; text: string } {
@@ -702,6 +749,7 @@ export function discardPreservedWorktrees(
 				branch: task.branch,
 				...(task.provider ? { provider: task.provider } : {}),
 				...(task.naming ? { naming: task.naming } : {}),
+				...(task.recordedBaseDir ? { recordedBaseDir: task.recordedBaseDir } : {}),
 				index: task.index,
 				nodeModulesLinked: false,
 				syntheticPaths: [],
@@ -738,4 +786,4 @@ export function discardPreservedWorktrees(
 		}
 	}
 	return { manifest, text: lines.join("\n") };
-}
+}

package/dist/extensions/pi-subagents/src/runs/shared/parallel-utils.ts

@@ -10,6 +10,10 @@ export interface RunnerSubagentStep {
 	sessionName?: string;
 	task: string;
 	runner?: ResolvedRunnerConfig;
+	/** Herdr saved machine this external-cli step runs on; `cwd` is then the directory on that machine. */
+	machine?: import("../../shared/types.ts").HerdrMachineReference;
+	remoteReads?: string[] | false;
+	machineEnv?: Record<string, string>;
 	externalJobFollowUp?: {
 		sourceRunId: string;
 		sourceStepIndex: number;
@@ -36,8 +40,10 @@ export interface RunnerSubagentStep {
 	contextLimit?: number;
 	fast?: boolean;
 	thinking?: string;
+	/** Trailing Claude Code argv for an explicit model/thinking request. */
+	claudeCodeOverrideArgs?: string[];
 	thinkingCeiling?: import("../../shared/model-info.ts").ThinkingLevel;
-	modelCandidates?: string[];
+	requestedModel?: string;
 	/** The primary model is inherited from the parent session and should not be verified against the child-reported active registry model. */
 	skipPrimaryModelVerification?: boolean;
 	modelVerificationRegistry?: Array<{ provider: string; id: string; fullId: string; contextWindow?: number }>;
@@ -45,11 +51,16 @@ export interface RunnerSubagentStep {
 	tools?: string[];
 	excludeTools?: string[];
 	allowNestedSubagents?: boolean;
+	/** Resolved selected-agent policy for launches made by this child. */
+	allowedAgents?: string[];
 	extensions?: string[];
 	subagentOnlyExtensions?: string[];
+	/** Private immutable host policy snapshot serialized to the native runner. */
+	requiredExtensions?: import("../../shared/required-child-extensions.ts").RequiredChildExtensionSnapshot;
 	mcpDirectTools?: string[];
+	/** The parent's resolution of `mcpDirectTools` against Pi's built-in MCP; the runner has no host to repeat it. */
+	builtinMcpTools?: import("./mcp-direct-tool-grant.ts").ResolvedMcpDirectToolSelection[];
 	mutationTools?: string[];
-	completionGuard?: boolean;
 	systemPrompt?: string | null;
 	systemPromptMode?: "append" | "replace";
 	inheritProjectContext: boolean;
@@ -237,7 +248,6 @@ export interface ParallelTaskResult {
 	error?: string;
 	timedOut?: boolean;
 	model?: string;
-	attemptedModels?: string[];
 	outputTargetPath?: string;
 	outputTargetExists?: boolean;
 }
@@ -271,4 +281,4 @@ export function aggregateParallelOutputs(
 		.join("\n\n");
 }
 
-export const MAX_PARALLEL_CONCURRENCY = 4;
+export const MAX_PARALLEL_CONCURRENCY = 4;

package/dist/extensions/pi-subagents/src/runs/shared/partial-output.ts

@@ -0,0 +1,48 @@
+/**
+ * Unfinished assistant text recovered when a child ends abnormally.
+ *
+ * Final output is built from completed `message_end` messages, so text that was
+ * still streaming when a child timed out or its session threw is otherwise lost.
+ * The tracker keeps one in-memory reference to the latest unfinished assistant
+ * message. Nothing is persisted.
+ */
+import type { ChildSessionEvent } from "./child-session.ts";
+import { extractTextFromContent } from "../../shared/utils.ts";
+
+export type PartialOutputCause = "timeout" | "child error";
+
+export interface PartialOutputTracker {
+	observe(event: ChildSessionEvent): void;
+	/** Latest unfinished assistant text that is newer than the last completed reply. */
+	text(): string | undefined;
+}
+
+function isAssistant(message: unknown): boolean {
+	return !!message && typeof message === "object" && (message as { role?: unknown }).role === "assistant";
+}
+
+function isErroredAssistant(message: unknown): boolean {
+	const { stopReason, errorMessage } = message as { stopReason?: unknown; errorMessage?: unknown };
+	return stopReason === "error" || (typeof errorMessage === "string" && errorMessage.length > 0);
+}
+
+export function createPartialOutputTracker(): PartialOutputTracker {
+	// Only a reference is kept per event; text is extracted once, when a child ends abnormally.
+	let latest: { content?: unknown } | undefined;
+	return {
+		observe(event) {
+			if ((event.type !== "message_update" && event.type !== "message_end") || !isAssistant(event.message)) return;
+			// A completed reply, including a tool-only one, is already part of the final output.
+			// A provider-error message is skipped there, so its text is the newest unfinished text.
+			latest = event.type === "message_update" || isErroredAssistant(event.message) ? event.message as { content?: unknown } : undefined;
+		},
+		text() {
+			const text = extractTextFromContent(latest?.content);
+			return text.trim() ? text : undefined;
+		},
+	};
+}
+
+export function formatPartialOutput(text: string, cause: PartialOutputCause): string {
+	return `Partial output before ${cause}:\n${text}`;
+}

package/dist/extensions/pi-subagents/src/runs/shared/pi-spawn.ts

@@ -6,9 +6,7 @@ import { SELESAI_CODING_AGENT_PACKAGE_ROOT_ENV } from "../../shared/utils.ts";
 export const SELESAI_CODING_AGENT_PACKAGE = "@selesai/code";
 export const SELESAI_SUBAGENT_SELESAI_BINARY_ENV = "SELESAI_SUBAGENT_SELESAI_BINARY";
 
-export function findPiPackageRootFromEntry(
-	entryPoint: string,
-): string | undefined {
+export function findPiPackageRootFromEntry(entryPoint: string): string | undefined {
 	let dir = path.dirname(entryPoint);
 	while (dir !== path.dirname(dir)) {
 		const packageJsonPath = path.join(dir, "package.json");
@@ -49,6 +47,7 @@ export interface PiSpawnDeps {
 	platform?: NodeJS.Platform;
 	execPath?: string;
 	argv1?: string;
+	bunVersion?: string;
 	existsSync?: (filePath: string) => boolean;
 	realpathSync?: (filePath: string) => string;
 	readFileSync?: (filePath: string, encoding: "utf-8") => string;
@@ -58,6 +57,15 @@ export interface PiSpawnDeps {
 	env?: NodeJS.ProcessEnv;
 }
 
+/** Compiled Pi's entrypoint is virtual; execPath is the real (possibly renamed) image. */
+export function resolveBunPiExecutable(deps: PiSpawnDeps = {}): string | undefined {
+	const bunVersion = deps.bunVersion ?? process.versions.bun;
+	const entry = deps.argv1 ?? process.argv[1];
+	if (!bunVersion || !entry || !/^(?:\/\$bunfs\/|B:[\\/]~BUN[\\/])/.test(entry)) return undefined;
+	const env = deps.env ?? process.env;
+	return env[SELESAI_SUBAGENT_SELESAI_BINARY_ENV]?.trim() || (deps.execPath ?? process.execPath);
+}
+
 interface PiSpawnCommand {
 	command: string;
 	args: string[];
@@ -196,4 +204,4 @@ export function getPiSpawnCommand(
 	}
 
 	return { command: "selesai", args };
-}
+}

package/dist/extensions/pi-subagents/src/runs/shared/run-history.ts

@@ -133,6 +133,93 @@ function appendPrivateHistoryLine(historyPath: string, line: string): void {
 	}
 }
 
+function backgroundRunHistoryTask(steps: readonly unknown[], resultMode: string): string {
+	const step = steps.length === 1 && typeof steps[0] === "object" && steps[0] !== null
+		? (steps[0] as { task?: unknown; launchBindingTask?: unknown })
+		: undefined;
+	if (step) {
+		const task = typeof step.launchBindingTask === "string" && step.launchBindingTask ? step.launchBindingTask : step.task;
+		if (typeof task === "string" && task) return task;
+	}
+	return resultMode || "run";
+}
+
+export interface BackgroundRunHistoryEntry {
+	agent: string;
+	task: string;
+	exitCode: number;
+	durationMs: number;
+	terminal: Pick<NonNullable<Parameters<typeof recordRun>[4]>, "stopped" | "interrupted" | "timedOut" | "processSignal">;
+}
+
+const TERMINAL_STEP_STATUSES = new Set(["complete", "completed"]);
+/** Steps that reached THEIR OWN terminal state — run-wide flags must not relabel them. */
+const SELF_TERMINAL_STEP_STATUSES = new Set(["complete", "completed", "failed", "rejected"]);
+
+/**
+ * Census rows for one finished background run. Single-step runs keep the exact
+ * foreground shape (agent + task text). Multi-step runs record ONE ROW PER CHILD
+ * STEP so `loadRunsForAgent(agent)` sees every child — a composite-only row would
+ * stay invisible to per-agent lookups. Per-step prompts are never hashed:
+ * multi-step rows hash the mode label only.
+ *
+ * Fidelity rules:
+ * - a row is recorded only for children that actually LAUNCHED (a child
+ *   session was dispatched). Status alone cannot decide this: `stopRunner()`,
+ *   `timeoutRunner()`, fail-fast skips, and usage-budget skips all relabel
+ *   never-launched steps to terminal statuses (`stopped`, `failed`+`timedOut,
+ *   `failed`+`skipped) before the run ends — the runner therefore threads an
+ *   explicit `launched` fact per step. `pending` and `launched: false` steps
+ *   get no row — unrun agents must not accumulate attempts or failures;
+ * - run-level terminal flags (stopped/interrupted/timedOut) apply only to steps
+ *   that did not reach a terminal state of their own — a child that completed
+ *   or failed BEFORE a sibling was interrupted keeps its own outcome, because
+ *   recordRun() lets those flags override the exit code;
+ * - self-terminal steps carry their own timedOut/stopped flags instead.
+ */
+export function planBackgroundRunHistory(input: {
+	steps: readonly unknown[];
+	resultMode: string;
+	statusSteps: ReadonlyArray<{ agent?: unknown; status?: unknown; durationMs?: number; timedOut?: boolean; stopped?: boolean; launched?: boolean }>;
+	stepResults?: ReadonlyArray<{ processSignal?: unknown } | undefined>;
+	runDurationMs: number;
+	stopped?: boolean;
+	interrupted?: boolean;
+	timedOut?: boolean;
+}): BackgroundRunHistoryEntry[] {
+	const runTerminal: BackgroundRunHistoryEntry["terminal"] = {
+		...(input.stopped ? { stopped: true } : {}),
+		...(input.interrupted ? { interrupted: true } : {}),
+		...(input.timedOut ? { timedOut: true } : {}),
+	};
+	const task = backgroundRunHistoryTask(input.steps, input.resultMode);
+	const rows: BackgroundRunHistoryEntry[] = [];
+	for (const [index, step] of input.statusSteps.entries()) {
+		if (typeof step.agent !== "string" || !step.agent) continue;
+		// `launched === false` marks steps the runner never dispatched a child
+		// session for, regardless of the status they were later relabeled to.
+		if (step.status === "pending" || step.launched === false) continue;
+		const succeeded = typeof step.status === "string" && TERMINAL_STEP_STATUSES.has(step.status);
+		const ownTerminal: BackgroundRunHistoryEntry["terminal"] = {
+			...(step.timedOut === true ? { timedOut: true } : {}),
+			...(step.stopped === true ? { stopped: true } : {}),
+		};
+		// A step that reached its own terminal state (completed, or failed/rejected
+		// before a sibling was interrupted) keeps its own outcome; run-wide flags
+		// would relabel it in recordRun().
+		const terminal = typeof step.status === "string" && SELF_TERMINAL_STEP_STATUSES.has(step.status) ? ownTerminal : { ...runTerminal, ...ownTerminal };
+		const processSignal = input.stepResults?.[index]?.processSignal;
+		rows.push({
+			agent: step.agent,
+			task,
+			exitCode: succeeded ? 0 : 1,
+			durationMs: typeof step.durationMs === "number" ? step.durationMs : input.runDurationMs,
+			terminal: processSignal === undefined ? terminal : { ...terminal, processSignal: typeof processSignal === "string" ? processSignal : null },
+		});
+	}
+	return rows;
+}
+
 export function recordRun(
 	agent: string,
 	task: string,
@@ -198,4 +285,4 @@ export function loadRunsForAgent(agent: string): RunEntry[] {
 		.map((line) => { try { return JSON.parse(line) as RunEntry; } catch { return undefined; } })
 		.filter((entry): entry is RunEntry => entry !== undefined && entry.agent === agent)
 		.reverse();
-}
+}

package/dist/extensions/pi-subagents/src/runs/shared/single-output.ts

@@ -2,7 +2,16 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { Message } from "@earendil-works/pi-ai";
 import type { OutputMode, SavedOutputReference } from "../../shared/types.ts";
-import { hasMutationToolCapability } from "./completion-guard.ts";
+
+const READ_ONLY_OUTPUT_TOOLS = new Set([
+	"read", "grep", "find", "ls", "web_search", "fetch_content", "get_search_content",
+	"source_check", "intercom", "contact_supervisor", "structured_output", "watchdog_diff",
+]);
+
+function hasOutputWriteCapability(tools: string[] | undefined, mcpDirectTools: string[] | undefined): boolean {
+	if ((mcpDirectTools?.length ?? 0) > 0 || tools === undefined) return true;
+	return tools.some((tool) => !READ_ONLY_OUTPUT_TOOLS.has(tool));
+}
 
 export interface SingleOutputSnapshot {
 	exists: boolean;
@@ -93,7 +102,7 @@ interface OutputInstructionCapabilities {
 }
 
 function formatOutputPathInstruction(outputPath: string, capabilities?: OutputInstructionCapabilities): string {
-	const delivery = !capabilities || hasMutationToolCapability(capabilities.tools, capabilities.mcpDirectTools)
+	const delivery = !capabilities || hasOutputWriteCapability(capabilities.tools, capabilities.mcpDirectTools)
 		? `Write your findings to exactly this path: ${outputPath}`
 		: [
 			"Return the complete artifact in your final response.",
@@ -301,4 +310,4 @@ export function finalizeSingleOutput(params: {
 		return { displayOutput, saveError: params.saveError };
 	}
 	return { displayOutput };
-}
+}

package/dist/extensions/pi-subagents/src/runs/shared/structured-output.ts

@@ -53,7 +53,7 @@ function sanitizeStructuredOutputRejection(text: string): string {
 			&& !/^(?:arguments?|parameters?|submitted value|input|outputSchema|schema|stack)\s*:/i.test(trimmed);
 	});
 	const sanitized = lines.join("\n")
-		.replace(/\b(received|actual|got)(?:\s+value)?\s*[:=]\s*(?:\"(?:[^\"\\\\]|\\\\.)*\"|'(?:[^'\\\\]|\\\\.)*'|\{[^\n]*\}|\[[^\n]*\]|\S+)/gi, "$1: [redacted]")
+		.replace(/\b(received|actual|got)(?:\s+value)?\s*[:=]\s*(?:"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|\{[^\n]*\}|\[[^\n]*\]|\S+)/gi, "$1: [redacted]")
 		.trim();
 	return sanitized || STRUCTURED_OUTPUT_REJECTION_ERROR;
 }
@@ -144,7 +144,15 @@ export function createStructuredOutputToolParameters(schema: JsonSchemaObject, o
 
 interface CompiledJsonSchema {
 	Check(value: unknown): boolean;
-	Errors(value: unknown): Iterable<{ instancePath?: string; message?: string }>;
+	Errors(value: unknown): Iterable<JsonSchemaValidationError>;
+}
+
+interface JsonSchemaValidationError {
+	keyword?: string;
+	schemaPath?: string;
+	instancePath?: string;
+	params?: { failingKeyword?: string; requiredProperties?: string[] };
+	message?: string;
 }
 
 type CompileJsonSchema = (schema: unknown) => CompiledJsonSchema;
@@ -192,6 +200,142 @@ function loadCompile(): Promise<CompileJsonSchema> {
 	return cachedCompile;
 }
 
+function jsonPointerTarget(root: unknown, pointer: string): unknown {
+	if (pointer === "#") return root;
+	if (!pointer.startsWith("#/")) return undefined;
+	let current = root;
+	for (const encoded of pointer.slice(2).split("/")) {
+		if (!current || typeof current !== "object") return undefined;
+		const key = encoded.replace(/~1/g, "/").replace(/~0/g, "~");
+		current = (current as Record<string, unknown>)[key];
+	}
+	return current;
+}
+
+function resolveLocalRefs(root: unknown, node: unknown): Record<string, unknown> | undefined {
+	const seen = new Set<unknown>();
+	while (node && typeof node === "object" && !Array.isArray(node) && !seen.has(node)) {
+		seen.add(node);
+		const record = node as Record<string, unknown>;
+		if (typeof record.$ref !== "string" || !record.$ref.startsWith("#")) return record;
+		node = jsonPointerTarget(root, record.$ref);
+	}
+	return undefined;
+}
+
+type InstanceSchemaStep = { kind: "property"; key: string } | { kind: "index"; index: number };
+
+function traverseInstanceSchema(root: unknown, instancePath: string | undefined): { node: Record<string, unknown>; steps: InstanceSchemaStep[] } | undefined {
+	let node = resolveLocalRefs(root, root);
+	const steps: InstanceSchemaStep[] = [];
+	for (const encoded of instancePath?.replace(/^\//, "").split("/") ?? []) {
+		if (!encoded || !node) continue;
+		const key = encoded.replace(/~1/g, "/").replace(/~0/g, "~");
+		const properties = node.properties;
+		if (properties && typeof properties === "object" && !Array.isArray(properties) && key in properties) {
+			steps.push({ kind: "property", key });
+			node = resolveLocalRefs(root, (properties as Record<string, unknown>)[key]);
+			continue;
+		}
+		if (/^(0|[1-9]\d*)$/.test(key)) {
+			const index = Number(key);
+			const prefixItems = node.prefixItems;
+			const itemSchema = Array.isArray(prefixItems) && index < prefixItems.length ? prefixItems[index] : node.items;
+			if (itemSchema !== undefined) {
+				steps.push({ kind: "index", index });
+				node = resolveLocalRefs(root, itemSchema);
+				continue;
+			}
+		}
+		return undefined;
+	}
+	return node ? { node, steps } : undefined;
+}
+
+function conditionalTarget(root: unknown, schemaPath: string, instancePath: string | undefined): { node: Record<string, unknown>; steps: InstanceSchemaStep[] } | undefined {
+	const traversed = traverseInstanceSchema(root, instancePath);
+	if (!traversed) return undefined;
+	let pointer = schemaPath;
+	const seen = new Set<string>();
+	while (!seen.has(pointer)) {
+		seen.add(pointer);
+		const record = resolveLocalRefs(root, jsonPointerTarget(root, pointer));
+		if (!record) break;
+		if (record.if !== undefined) return { node: record, steps: traversed.steps };
+		if (typeof record.$ref !== "string" || !record.$ref.startsWith("#")) break;
+		pointer = record.$ref;
+	}
+	if (traversed.node.if !== undefined) return traversed;
+	return undefined;
+}
+
+function errorKey(error: JsonSchemaValidationError): string {
+	return JSON.stringify([error.keyword, error.instancePath, error.params, error.message]);
+}
+
+function branchDiagnosticSchema(schema: JsonSchemaObject, steps: InstanceSchemaStep[], branch: unknown): JsonSchemaObject {
+	const diagnostic: Record<string, unknown> = {};
+	for (const keyword of ["$schema", "$id", "$defs", "definitions"] as const) {
+		if (schema[keyword] !== undefined) diagnostic[keyword] = schema[keyword];
+	}
+	let target = diagnostic;
+	for (const step of steps) {
+		if (step.kind === "index") {
+			const index = step.index;
+			const prefixItems = Array.from({ length: index + 1 }, () => true as unknown);
+			const nested: Record<string, unknown> = {};
+			prefixItems[index] = nested;
+			target.prefixItems = prefixItems;
+			target.items = true;
+			target = nested;
+		} else {
+			const nested: Record<string, unknown> = {};
+			target.properties = { [step.key]: nested };
+			target = nested;
+		}
+	}
+	target.allOf = [branch];
+	return diagnostic as JsonSchemaObject;
+}
+
+function expandConditionalError(compile: CompileJsonSchema, schema: JsonSchemaObject, value: unknown, error: JsonSchemaValidationError): { schema: JsonSchemaObject; errors: JsonSchemaValidationError[] } | undefined {
+	const branch = error.params?.failingKeyword;
+	if (error.keyword !== "if" || (branch !== "then" && branch !== "else") || !error.schemaPath) return undefined;
+	try {
+		const target = conditionalTarget(schema, error.schemaPath, error.instancePath);
+		if (!target || target.node[branch] === undefined) return undefined;
+		const expandedSchema = branchDiagnosticSchema(schema, target.steps, target.node[branch]);
+		const expandedErrors = [...compile(expandedSchema).Errors(value)];
+		if (expandedErrors.length === 0) return undefined;
+		return { schema: expandedSchema, errors: expandedErrors };
+	} catch {
+		return undefined;
+	}
+}
+
+function formatValidationError(error: JsonSchemaValidationError): string[] {
+	const pathText = error.instancePath ? error.instancePath.replace(/^\//, "").replace(/\//g, ".") : "root";
+	if (error.keyword === "required" && error.params?.requiredProperties?.length) {
+		return error.params.requiredProperties.map((property) => `${pathText === "root" ? property : `${pathText}.${property}`}: is required`);
+	}
+	return [`${pathText}: ${error.message}`];
+}
+
+function expandedErrorMessages(compile: CompileJsonSchema, schema: JsonSchemaObject, value: unknown, error: JsonSchemaValidationError, limit: number, seen: Set<string>): string[] {
+	if (limit <= 0) return [];
+	const state = `${errorKey(error)}\0${JSON.stringify(schema)}`;
+	if (seen.has(state)) return formatValidationError(error).slice(0, limit);
+	seen.add(state);
+	const expanded = expandConditionalError(compile, schema, value, error);
+	if (!expanded) return formatValidationError(error).slice(0, limit);
+	const messages: string[] = [];
+	for (const candidate of expanded.errors) {
+		messages.push(...expandedErrorMessages(compile, expanded.schema, value, candidate, limit - messages.length, seen));
+		if (messages.length >= limit) break;
+	}
+	return messages;
+}
+
 export function assertJsonSchemaObject(schema: unknown, label = "outputSchema"): asserts schema is JsonSchemaObject {
 	if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
 		throw new Error(`${label} must be a JSON Schema object.`);
@@ -225,12 +369,19 @@ export async function validateStructuredOutputValue(schema: JsonSchemaObject, va
 		return { status: "invalid", message: `invalid outputSchema: ${error instanceof Error ? error.message : String(error)}` };
 	}
 	if (validator.Check(value)) return { status: "valid" };
-	const errors = [...validator.Errors(value)]
-		.slice(0, 8)
-		.map((error) => {
-			const pathText = error.instancePath ? error.instancePath.replace(/^\//, "").replace(/\//g, ".") : "root";
-			return `${pathText}: ${error.message}`;
-		});
+	const originalErrors = [...validator.Errors(value)];
+	const errors: string[] = [];
+	const uniqueErrors = new Set<string>();
+	const seen = new Set<string>();
+	for (const error of originalErrors) {
+		for (const message of expandedErrorMessages(compile, schema, value, error, 8 - errors.length, seen)) {
+			if (!uniqueErrors.has(message)) {
+				uniqueErrors.add(message);
+				errors.push(message);
+			}
+		}
+		if (errors.length >= 8) break;
+	}
 	return { status: "invalid", message: errors.join("; ") || "schema validation failed" };
 }
 
@@ -302,4 +453,4 @@ export function cleanupStructuredOutputRuntime(runtime: StructuredOutputRuntime
 	} catch {
 		// Best-effort temp cleanup.
 	}
-}
+}