@oh-my-pi/pi-coding-agent 16.2.6 → 16.2.8

package/src/task/worktree.ts

@@ -148,21 +148,33 @@ export async function captureBaseline(repoRoot: string): Promise<WorktreeBaselin
 	return { root, nested };
 }
 
-async function captureRepoDeltaPatch(repoDir: string, rb: RepoBaseline): Promise<string> {
+async function captureRepoDeltaPatch(repoDir: string, rb: RepoBaseline, objectRepoDir = repoDir): Promise<string> {
 	const currentHead = (await git.head.sha(repoDir)) ?? "";
 	const currentStaged = await git.diff(repoDir, { binary: true, cached: true });
 	const currentUnstaged = await git.diff(repoDir, { binary: true });
 	const currentUntracked = await git.ls.untracked(repoDir);
 	const currentUntrackedPatch = await captureUntrackedPatch(repoDir, currentUntracked);
-
-	const baselineTree = await writeSyntheticTree(repoDir, rb.headCommit, [rb.staged, rb.unstaged, rb.untrackedPatch]);
-	const currentTree = await writeSyntheticTree(repoDir, currentHead, [
+	const committedPatch =
+		currentHead && currentHead !== rb.headCommit
+			? await git.diff.tree(repoDir, rb.headCommit, currentHead, {
+					allowFailure: true,
+					binary: true,
+				})
+			: "";
+
+	const baselineTree = await writeSyntheticTree(objectRepoDir, rb.headCommit, [
+		rb.staged,
+		rb.unstaged,
+		rb.untrackedPatch,
+	]);
+	const currentTree = await writeSyntheticTree(objectRepoDir, rb.headCommit, [
+		committedPatch,
 		currentStaged,
 		currentUnstaged,
 		currentUntrackedPatch,
 	]);
 
-	return git.diff.tree(repoDir, baselineTree, currentTree, {
+	return git.diff.tree(objectRepoDir, baselineTree, currentTree, {
 		allowFailure: true,
 		binary: true,
 	});
@@ -212,7 +224,7 @@ export interface DeltaPatchResult {
 }
 
 export async function captureDeltaPatch(isolationDir: string, baseline: WorktreeBaseline): Promise<DeltaPatchResult> {
-	const rootPatch = await captureRepoDeltaPatch(isolationDir, baseline.root);
+	const rootPatch = await captureRepoDeltaPatch(isolationDir, baseline.root, baseline.root.repoRoot);
 	const nestedPatches: NestedRepoPatch[] = [];
 
 	for (const { relativePath, baseline: nb } of baseline.nested) {
@@ -222,7 +234,7 @@ export async function captureDeltaPatch(isolationDir: string, baseline: Worktree
 		} catch {
 			continue;
 		}
-		const patch = await captureRepoDeltaPatch(nestedDir, nb);
+		const patch = await captureRepoDeltaPatch(nestedDir, nb, nb.repoRoot);
 		if (patch.trim()) nestedPatches.push({ relativePath, patch });
 	}
 
@@ -460,12 +472,137 @@ export async function cleanupIsolation(handle: IsolationHandle): Promise<void> {
 export interface CommitToBranchResult {
 	branchName?: string;
 	nestedPatches: NestedRepoPatch[];
+	/**
+	 * SHA of the parent-repo commit the task branch was created on top of, so
+	 * {@link mergeTaskBranches} can cherry-pick the range `baseSha..branchName`
+	 * and preserve every agent commit's message and author.
+	 */
+	baseSha?: string;
+}
+
+function baselineHasRootWip(baseline: RepoBaseline): boolean {
+	return !!(baseline.staged.trim() || baseline.unstaged.trim() || baseline.untrackedPatch.trim());
+}
+
+async function commitPatchToBranchWorktree(
+	tmpDir: string,
+	taskId: string,
+	patchText: string,
+	message: string,
+	author?: git.CommitAuthor,
+): Promise<void> {
+	try {
+		await git.patch.applyText(tmpDir, patchText);
+	} catch (err) {
+		if (!(err instanceof git.GitCommandError)) throw err;
+		// Plain apply rejects when the parent checkout carries unrelated dirty
+		// context near the task's edits; retry with --3way before giving up.
+		try {
+			await git.patch.applyText(tmpDir, patchText, { threeWay: true });
+		} catch (threeWayErr) {
+			if (threeWayErr instanceof git.GitCommandError) {
+				const stderr = threeWayErr.result.stderr.slice(0, 2000);
+				logger.error("commitToBranch: git apply --3way failed", {
+					taskId,
+					exitCode: threeWayErr.result.exitCode,
+					stderr,
+					initialStderr: err.result.stderr.slice(0, 2000),
+					patchSize: patchText.length,
+					patchHead: patchText.slice(0, 500),
+				});
+				throw new Error(`git apply --3way failed for task ${taskId}: ${stderr}`);
+			}
+			throw threeWayErr;
+		}
+	}
+	await git.stage.files(tmpDir);
+	await git.commit(tmpDir, message, author ? { author } : {});
+}
+
+interface FilteredAgentReplayOptions {
+	baseline: WorktreeBaseline;
+	branchName: string;
+	commitMessage?: (diff: string) => Promise<string | null>;
+	fallbackMessage: string;
+	isolationDir: string;
+	isolationHead: string;
+	repoRoot: string;
+	rootPatch: string;
+	taskId: string;
+}
+
+async function replayFilteredAgentCommits(opts: FilteredAgentReplayOptions): Promise<void> {
+	const baselineSha = opts.baseline.root.headCommit;
+	await git.branch.create(opts.repoRoot, opts.branchName, baselineSha);
+
+	const tmpDir = path.join(os.tmpdir(), `omp-branch-${Snowflake.next()}`);
+	try {
+		await git.worktree.add(opts.repoRoot, tmpDir, opts.branchName);
+		const agentCommits = await git.revList.range(opts.isolationDir, baselineSha, opts.isolationHead);
+		const dirtyBaselineTree = await writeSyntheticTree(opts.isolationDir, baselineSha, [
+			opts.baseline.root.staged,
+			opts.baseline.root.unstaged,
+			opts.baseline.root.untrackedPatch,
+		]);
+		let previousFilteredTree = baselineSha;
+
+		for (const commitSha of agentCommits) {
+			const taskStatePatch = await git.diff.tree(opts.isolationDir, dirtyBaselineTree, `${commitSha}^{tree}`, {
+				allowFailure: true,
+				binary: true,
+			});
+			const currentFilteredTree = await writeSyntheticTree(opts.repoRoot, baselineSha, [taskStatePatch]);
+			const commitPatch = await git.diff.tree(opts.repoRoot, previousFilteredTree, currentFilteredTree, {
+				allowFailure: true,
+				binary: true,
+			});
+			if (commitPatch.trim()) {
+				const details = await git.commitDetails(opts.isolationDir, commitSha);
+				await commitPatchToBranchWorktree(
+					tmpDir,
+					opts.taskId,
+					commitPatch,
+					details.message || commitSha,
+					details.author,
+				);
+			}
+			previousFilteredTree = currentFilteredTree;
+		}
+
+		const finalFilteredTree = await writeSyntheticTree(opts.repoRoot, baselineSha, [opts.rootPatch]);
+		const leftoverPatch = await git.diff.tree(opts.repoRoot, previousFilteredTree, finalFilteredTree, {
+			allowFailure: true,
+			binary: true,
+		});
+		if (leftoverPatch.trim()) {
+			const msg = (opts.commitMessage && (await opts.commitMessage(leftoverPatch))) || opts.fallbackMessage;
+			await commitPatchToBranchWorktree(tmpDir, opts.taskId, leftoverPatch, msg);
+		}
+	} finally {
+		await git.worktree.tryRemove(opts.repoRoot, tmpDir);
+		await fs.rm(tmpDir, { recursive: true, force: true });
+	}
 }
 
 /**
- * Commit task-only changes to a new branch.
- * Only root repo changes go on the branch. Nested repo patches are returned
- * separately since the parent git can't track files inside gitlinks.
+ * Capture task-only changes from the isolation worktree onto a parent-repo
+ * branch named `omp/task/${taskId}`. Only root-repo changes go on the branch;
+ * nested-repo patches are returned separately because the parent git can't
+ * track files inside gitlinks.
+ *
+ * If the agent committed inside isolation (HEAD moved past
+ * `baseline.root.headCommit`), clean-baseline runs fetch the raw commit range
+ * into the parent repo and later cherry-pick `baseSha..branchName`, preserving
+ * every message and author verbatim. Dirty-baseline runs rewrite each agent
+ * commit against the captured baseline WIP before committing it to the task
+ * branch, so user staged/unstaged/untracked changes present at isolation
+ * start are not replayed into the parent commit history.
+ *
+ * If the agent did not commit, the captured delta is collapsed onto a single
+ * branch commit with an AI-generated (or fallback) message — the legacy
+ * behaviour.
+ *
+ * Returns `null` when no root or nested changes exist.
  */
 export async function commitToBranch(
 	isolationDir: string,
@@ -474,45 +611,84 @@ export async function commitToBranch(
 	description: string | undefined,
 	commitMessage?: (diff: string) => Promise<string | null>,
 ): Promise<CommitToBranchResult | null> {
+	const baselineSha = baseline.root.headCommit;
+	const isolationHead = (await git.head.sha(isolationDir)) ?? "";
+	const agentCommitted = isolationHead !== "" && isolationHead !== baselineSha;
+
 	const { rootPatch, nestedPatches } = await captureDeltaPatch(isolationDir, baseline);
 	if (!rootPatch.trim() && nestedPatches.length === 0) return null;
+	if (!rootPatch.trim()) return { nestedPatches };
 
 	const repoRoot = baseline.root.repoRoot;
 	const branchName = `omp/task/${taskId}`;
 	const fallbackMessage = description || taskId;
 
-	// Only create a branch if the root repo has changes
-	if (rootPatch.trim()) {
-		await git.branch.create(repoRoot, branchName);
+	let branchCreated = false;
+
+	if (agentCommitted) {
+		if (baselineHasRootWip(baseline.root)) {
+			await replayFilteredAgentCommits({
+				baseline,
+				branchName,
+				commitMessage,
+				fallbackMessage,
+				isolationDir,
+				isolationHead,
+				repoRoot,
+				rootPatch,
+				taskId,
+			});
+		} else {
+			// Transfer the agent's commit objects (which live in isolation's `.git`,
+			// stranded once `cleanupIsolation` tears the overlay down) into the parent
+			// repo's object DB and create the branch at the agent's HEAD. `+HEAD:…`
+			// force-overwrites a stale branch from a prior run.
+			await git.fetch(repoRoot, isolationDir, "HEAD", `refs/heads/${branchName}`);
+
+			// Leftover = anything still uncommitted in isolation on top of the
+			// agent's last commit (staged, unstaged, untracked). The agent didn't
+			// commit it, so it goes in as one AI-summarized trailing commit.
+			const leftoverPatch = await captureRepoDeltaPatch(isolationDir, {
+				repoRoot: isolationDir,
+				headCommit: isolationHead,
+				staged: "",
+				unstaged: "",
+				untracked: [],
+				untrackedPatch: "",
+			});
+			if (leftoverPatch.trim()) {
+				const tmpDir = path.join(os.tmpdir(), `omp-branch-${Snowflake.next()}`);
+				try {
+					await git.worktree.add(repoRoot, tmpDir, branchName);
+					const msg = (commitMessage && (await commitMessage(leftoverPatch))) || fallbackMessage;
+					await commitPatchToBranchWorktree(tmpDir, taskId, leftoverPatch, msg);
+				} finally {
+					await git.worktree.tryRemove(repoRoot, tmpDir);
+					await fs.rm(tmpDir, { recursive: true, force: true });
+				}
+			}
+		}
+		branchCreated = true;
+	} else if (rootPatch.trim()) {
+		await git.branch.create(repoRoot, branchName, baselineSha);
+		branchCreated = true;
 		const tmpDir = path.join(os.tmpdir(), `omp-branch-${Snowflake.next()}`);
 		try {
 			await git.worktree.add(repoRoot, tmpDir, branchName);
-			try {
-				await git.patch.applyText(tmpDir, rootPatch);
-			} catch (err) {
-				if (err instanceof git.GitCommandError) {
-					const stderr = err.result.stderr.slice(0, 2000);
-					logger.error("commitToBranch: git apply failed", {
-						taskId,
-						exitCode: err.result.exitCode,
-						stderr,
-						patchSize: rootPatch.length,
-						patchHead: rootPatch.slice(0, 500),
-					});
-					throw new Error(`git apply failed for task ${taskId}: ${stderr}`);
-				}
-				throw err;
-			}
-			await git.stage.files(tmpDir);
+
 			const msg = (commitMessage && (await commitMessage(rootPatch))) || fallbackMessage;
-			await git.commit(tmpDir, msg);
+			await commitPatchToBranchWorktree(tmpDir, taskId, rootPatch, msg);
 		} finally {
 			await git.worktree.tryRemove(repoRoot, tmpDir);
 			await fs.rm(tmpDir, { recursive: true, force: true });
 		}
 	}
 
-	return { branchName: rootPatch.trim() ? branchName : undefined, nestedPatches };
+	return {
+		branchName: branchCreated ? branchName : undefined,
+		baseSha: baselineSha,
+		nestedPatches,
+	};
 }
 
 export interface MergeBranchResult {
@@ -524,13 +700,17 @@ export interface MergeBranchResult {
 }
 
 /**
- * Cherry-pick task branch commits sequentially onto HEAD.
- * Each branch has a single commit that gets replayed cleanly.
- * Stops on first conflict and reports which branches succeeded.
+ * Cherry-pick task branch commits sequentially onto HEAD. When `baseSha` is
+ * provided the cherry-pick uses the inclusive range `baseSha..branchName`,
+ * replaying every commit individually and preserving each commit's message
+ * and author. When omitted, the branch is cherry-picked as a single commit
+ * (legacy callers).
+ *
+ * Stops on the first conflict and reports which branches succeeded.
  */
 export async function mergeTaskBranches(
 	repoRoot: string,
-	branches: Array<{ branchName: string; taskId: string; description?: string }>,
+	branches: Array<{ branchName: string; taskId: string; description?: string; baseSha?: string }>,
 ): Promise<MergeBranchResult> {
 	// Serialize against other in-process git mutations on this repo: concurrent
 	// background merges interleaving stash push/pop + cherry-pick would corrupt
@@ -546,9 +726,10 @@ export async function mergeTaskBranches(
 		let conflictResult: MergeBranchResult | undefined;
 
 		try {
-			for (const { branchName } of branches) {
+			for (const { branchName, baseSha } of branches) {
 				try {
-					await git.cherryPick(repoRoot, branchName);
+					const target = baseSha ? `${baseSha}..${branchName}` : branchName;
+					await git.cherryPick(repoRoot, target);
 				} catch (err) {
 					try {
 						await git.cherryPick.abort(repoRoot);

package/src/tiny/title-client.ts

@@ -29,7 +29,12 @@ import type { TinyTitleProgressEvent, TinyTitleWorkerInbound, TinyTitleWorkerOut
 type PendingRequest =
 	| { kind: "generate"; modelKey: TinyTitleLocalModelKey; resolve: (title: string | null) => void }
 	| { kind: "complete"; modelKey: TinyMemoryLocalModelKey; resolve: (text: string | null) => void }
-	| { kind: "download"; modelKey: TinyLocalModelKey; resolve: (ok: boolean) => void };
+	| { kind: "download"; modelKey: TinyLocalModelKey; resolve: (result: TinyTitleDownloadResult) => void };
+
+export interface TinyTitleDownloadResult {
+	ok: boolean;
+	error?: string;
+}
 
 export interface TinyTitleDownloadOptions {
 	signal?: AbortSignal;
@@ -269,21 +274,21 @@ export class TinyTitleClient {
 		}
 	}
 
-	async downloadModel(modelKey: string, options: TinyTitleDownloadOptions = {}): Promise<boolean> {
-		if (!isTinyLocalModelKey(modelKey)) return false;
-		if (options.signal?.aborted) return false;
+	async downloadModel(modelKey: string, options: TinyTitleDownloadOptions = {}): Promise<TinyTitleDownloadResult> {
+		if (!isTinyLocalModelKey(modelKey)) return { ok: false };
+		if (options.signal?.aborted) return { ok: false };
 
 		const unsubscribe = options.onProgress ? this.onProgress(options.onProgress) : undefined;
 		try {
 			const worker = this.#ensureWorker();
 			const id = String(++this.#nextRequestId);
-			const { promise, resolve } = Promise.withResolvers<boolean>();
+			const { promise, resolve } = Promise.withResolvers<TinyTitleDownloadResult>();
 			this.#addPending(id, { kind: "download", modelKey, resolve });
 			const abort = (): void => {
 				const pending = this.#pending.get(id);
 				if (pending?.kind !== "download") return;
 				this.#deletePending(id);
-				pending.resolve(false);
+				pending.resolve({ ok: false });
 			};
 			options.signal?.addEventListener("abort", abort, { once: true });
 			try {
@@ -294,11 +299,12 @@ export class TinyTitleClient {
 				this.#deletePending(id);
 			}
 		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
 			logger.debug("tiny-title: local model download failed", {
 				modelKey,
-				error: error instanceof Error ? error.message : String(error),
+				error: message,
 			});
-			return false;
+			return { ok: false, error: message };
 		} finally {
 			unsubscribe?.();
 		}
@@ -314,7 +320,7 @@ export class TinyTitleClient {
 		for (const pending of this.#pending.values()) {
 			this.#emitProgress({ modelKey: pending.modelKey, status: "error" });
 			if (pending.kind === "generate" || pending.kind === "complete") pending.resolve(null);
-			else pending.resolve(false);
+			else pending.resolve({ ok: false });
 		}
 		this.#pending.clear();
 		this.#refed = false;
@@ -379,7 +385,7 @@ export class TinyTitleClient {
 			return;
 		}
 		if (message.type === "downloaded") {
-			if (pending.kind === "download") pending.resolve(true);
+			if (pending.kind === "download") pending.resolve({ ok: true });
 			return;
 		}
 		if (message.type === "completion") {
@@ -389,8 +395,8 @@ export class TinyTitleClient {
 		logger.debug("tiny-title: worker returned error", { error: message.error });
 		this.#markFailedModel(pending);
 		this.#emitProgress({ modelKey: pending.modelKey, status: "error" });
-		if (pending.kind === "generate" || pending.kind === "complete") pending.resolve(null);
-		else pending.resolve(false);
+		if (pending.kind === "download") pending.resolve({ ok: false, error: message.error });
+		else pending.resolve(null);
 		void this.terminate();
 	}
 
@@ -407,7 +413,7 @@ export class TinyTitleClient {
 		for (const pending of this.#pending.values()) {
 			this.#emitProgress({ modelKey: pending.modelKey, status: "error" });
 			if (pending.kind === "generate" || pending.kind === "complete") pending.resolve(null);
-			else pending.resolve(false);
+			else pending.resolve({ ok: false, error: error.message });
 		}
 		this.#pending.clear();
 		void this.terminate();

package/src/tools/grep.ts

@@ -85,8 +85,26 @@ const searchSchema = type({
 });
 
 export type GrepToolInput = typeof searchSchema.infer;
+function parseStringEncodedPathArray(input: string): string[] | null {
+	const trimmed = input.trim();
+	if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) return null;
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(trimmed);
+	} catch {
+		return null;
+	}
+
+	if (!Array.isArray(parsed) || parsed.some(entry => typeof entry !== "string")) {
+		return null;
+	}
+	return parsed;
+}
+
 export function toPathList(input: string | string[] | undefined): string[] {
-	return typeof input === "string" ? [input] : (input ?? []);
+	if (typeof input === "string") return parseStringEncodedPathArray(input) ?? [input];
+	return input ?? [];
 }
 
 /** Maximum number of distinct files surfaced in a single response. The

package/src/tools/index.ts

@@ -1,6 +1,6 @@
 import type { InMemorySnapshotStore } from "@oh-my-pi/hashline";
 import type { AgentTelemetryConfig, AgentTool } from "@oh-my-pi/pi-agent-core";
-import type { FetchImpl, ImageContent, Model, ServiceTier, ToolChoice } from "@oh-my-pi/pi-ai";
+import type { FetchImpl, ImageContent, Model, ServiceTierByFamily, ToolChoice } from "@oh-my-pi/pi-ai";
 import { logger } from "@oh-my-pi/pi-utils";
 import type { AsyncJobManager } from "../async/job-manager";
 import type { Rule } from "../capability/rule";
@@ -240,8 +240,8 @@ export interface ToolSession {
 	getActiveModelString?: () => string | undefined;
 	/** Get the current session model object (provider/api capabilities), regardless of how it was chosen. */
 	getActiveModel?: () => Model | undefined;
-	/** Get the session's live effective service tier (undefined = none). Source of truth for subagent `serviceTierSubagent: inherit`. */
-	getServiceTier?: () => ServiceTier | undefined;
+	/** Get the session's live per-family service tiers (undefined = none). Source of truth for subagent `tier.subagent: inherit`. */
+	getServiceTierByFamily?: () => ServiceTierByFamily | undefined;
 	/** Auth storage for passing to subagents (avoids re-discovery) */
 	authStorage?: import("../session/auth-storage").AuthStorage;
 	/** Model registry for passing to subagents (avoids re-discovery) */

package/src/tools/irc.ts

@@ -172,7 +172,7 @@ export class IrcTool implements AgentTool<typeof ircSchema, IrcDetails> {
 			case "wait":
 				return this.#executeWait(senderId, params, signal);
 			case "inbox":
-				return this.#executeInbox(senderId, params);
+				return this.#executeInbox(registry, senderId, params);
 			default:
 				return errorResult("Unknown irc op.", { op: params.op });
 		}
@@ -371,8 +371,14 @@ export class IrcTool implements AgentTool<typeof ircSchema, IrcDetails> {
 		};
 	}
 
-	#executeInbox(senderId: string, params: IrcParams): AgentToolResult<IrcDetails> {
-		const messages = IrcBus.global().inbox(senderId, { peek: params.peek });
+	#executeInbox(registry: AgentRegistry, senderId: string, params: IrcParams): AgentToolResult<IrcDetails> {
+		const busMessages = IrcBus.global().inbox(senderId, { peek: params.peek });
+		const session = registry.get(senderId)?.session;
+		const pendingMessages =
+			typeof session?.drainPendingIrcInboxMessages === "function"
+				? session.drainPendingIrcInboxMessages(senderId)
+				: [];
+		const messages = [...busMessages, ...pendingMessages].sort((a, b) => a.ts - b.ts);
 		if (messages.length === 0) {
 			return {
 				content: [{ type: "text", text: "Inbox empty." }],

package/src/tools/output-schema-validator.ts

@@ -21,6 +21,16 @@ export interface OutputValidator {
 	validate(value: unknown): JsonSchemaValidationResult;
 	/** Top-level required property names. Empty if the schema has no `required` array at root. */
 	readonly requiredFields: readonly string[];
+	/**
+	 * Per-label validators for incremental yields (`type: ["<label>"]`). Each entry validates the
+	 * `data` payload of a single section against the matching top-level property's sub-schema —
+	 * array-typed properties (e.g. `findings`) use the items schema since each yield contributes
+	 * one element, while scalar properties use the property schema directly. Unknown labels (not
+	 * top-level properties) have no entry and skip per-call validation. Lets the yield tool give
+	 * the model retry feedback on a section as soon as it arrives, instead of deferring every
+	 * mismatch to the parent's post-mortem `schema_violation`.
+	 */
+	readonly validateSection: ReadonlyMap<string, (value: unknown) => JsonSchemaValidationResult>;
 }
 
 export interface BuildOutputValidatorResult {
@@ -72,10 +82,38 @@ export function buildOutputValidator(schema: unknown): BuildOutputValidatorResul
 		validator: {
 			requiredFields: required,
 			validate: value => validateJsonSchemaValue(jsonSchemaRecord, value),
+			validateSection: buildSectionValidators(jsonSchemaRecord),
 		},
 	};
 }
 
+/**
+ * Build per-top-level-property validators for incremental yields.
+ *
+ * Each entry validates the `data` payload of one `type: ["<label>"]` section against the
+ * matching property's sub-schema — array-typed properties (e.g. `findings`, derived from JTD
+ * `elements`) use the items schema since each yield contributes one element, while scalar
+ * properties use the property schema directly. Unknown labels (anything not declared as a
+ * top-level property) are deliberately omitted so user-defined section labels still pass.
+ */
+function buildSectionValidators(
+	jsonSchema: Record<string, unknown>,
+): ReadonlyMap<string, (value: unknown) => JsonSchemaValidationResult> {
+	const validators = new Map<string, (value: unknown) => JsonSchemaValidationResult>();
+	const properties = jsonSchema.properties;
+	if (properties === null || typeof properties !== "object") return validators;
+	for (const [label, raw] of Object.entries(properties as Record<string, unknown>)) {
+		if (raw === null || typeof raw !== "object") continue;
+		const propRecord = raw as Record<string, unknown>;
+		const sectionSchema =
+			propRecord.type === "array" && propRecord.items !== undefined && propRecord.items !== null
+				? (propRecord.items as Record<string, unknown>)
+				: propRecord;
+		validators.set(label, value => validateJsonSchemaValue(sectionSchema, value));
+	}
+	return validators;
+}
+
 /** Produce the executor's headline+missing-required summary from a failed validation. */
 export function summarizeValidationFailure(
 	result: JsonSchemaValidationResult,

package/src/tools/read.ts

@@ -14,7 +14,15 @@ import type { ImageContent, TextContent } from "@oh-my-pi/pi-ai";
 import { glob, type SummaryResult, summarizeCode } from "@oh-my-pi/pi-natives";
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
-import { getRemoteDir, type ImageMetadata, logger, prompt, readImageMetadata, untilAborted } from "@oh-my-pi/pi-utils";
+import {
+	getRemoteDir,
+	type ImageMetadata,
+	isProbablyBinary,
+	logger,
+	prompt,
+	readImageMetadata,
+	untilAborted,
+} from "@oh-my-pi/pi-utils";
 import { type } from "arktype";
 import { LRUCache } from "lru-cache/raw";
 import {
@@ -2314,6 +2322,25 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				content = [{ type: "text", text: `[Cannot read ${ext} file: conversion failed]` }];
 			}
 		} else {
+			// Binary sniff before any UTF-8 text materialization. A binary file
+			// (font, object, archive, packed blob) decodes to NUL/control bytes and
+			// U+FFFD mojibake that corrupts the terminal and burns context. Images,
+			// notebooks, and markit-convertible documents were already routed above;
+			// everything reaching here is meant to be plain text. `:raw` stays the
+			// explicit escape hatch for reading bytes verbatim. This single guard
+			// covers both the multi-range and single-range disk paths below.
+			if (!isRawSelector(parsed) && (await isProbablyBinary(absolutePath))) {
+				return toolResult<ReadToolDetails>({ resolvedPath: absolutePath, suffixResolution })
+					.text(
+						prependSuffixResolutionNotice(
+							`[Cannot read binary file '${formatPathRelativeToCwd(absolutePath, this.session.cwd)}' (${formatBytes(fileSize)}); not valid UTF-8 text. Use ':raw' to read bytes verbatim.]`,
+							suffixResolution,
+						),
+					)
+					.sourcePath(absolutePath)
+					.done();
+			}
+
 			if (
 				parsed.kind === "none" &&
 				this.session.settings.get("read.summarize.enabled") &&
@@ -2449,33 +2476,6 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 					// counts in `truncation` keep reflecting the source, not the trimmed
 					// view — column truncation surfaces separately via `.limits()`.
 					const rawSelector = isRawSelector(parsed);
-					// Binary sniff: NUL bytes mean the file is not displayable text
-					// (binary, or UTF-16 which has NULs in the ASCII range) — emit a
-					// notice instead of mojibake filling the line budget. `:raw`
-					// stays an explicit escape hatch.
-					//
-					// `collectedLines` covers the common case where at least one
-					// physical line terminates within the byte budget. Binary blobs
-					// without newlines (videos, archives, packed JSON) leave it
-					// empty; their bytes only land in `firstLinePreview`, which the
-					// `firstLineExceedsLimit` branch below would otherwise emit
-					// verbatim. Sniffing the preview here keeps the refusal uniform.
-					if (!rawSelector) {
-						const hasNul = (text: string): boolean => text.includes("\u0000");
-						const binaryDetected =
-							collectedLines.some(hasNul) || (firstLinePreview !== undefined && hasNul(firstLinePreview.text));
-						if (binaryDetected) {
-							return toolResult<ReadToolDetails>({ resolvedPath: absolutePath, suffixResolution })
-								.text(
-									prependSuffixResolutionNotice(
-										`[Cannot read binary file '${formatPathRelativeToCwd(absolutePath, this.session.cwd)}' (${formatBytes(fileSize)}); content contains NUL bytes (binary or UTF-16 encoded)]`,
-										suffixResolution,
-									),
-								)
-								.sourcePath(absolutePath)
-								.done();
-						}
-					}
 					const maxColumns = resolveOutputMaxColumns(this.session.settings);
 					// Column truncation is display-only. `collectedLines` MUST stay
 					// byte-for-byte with the on-disk content so the snapshot recorded