@oh-my-pi/pi-coding-agent 16.1.23 → 16.2.1

package/src/modes/acp/acp-agent.ts

@@ -42,7 +42,7 @@ import {
 } from "@agentclientprotocol/sdk";
 import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import type { AssistantMessage, Model } from "@oh-my-pi/pi-ai";
-import { isEnoent, logger, VERSION } from "@oh-my-pi/pi-utils";
+import { getBlobsDir, isEnoent, logger, VERSION } from "@oh-my-pi/pi-utils";
 import { disableProvider, enableProvider, reset as resetCapabilities } from "../../capability";
 import { Settings } from "../../config/settings";
 import { clearPluginRootsAndCaches, resolveActiveProjectRegistryPath } from "../../discovery/helpers";
@@ -62,6 +62,7 @@ import { loadAllExtensions } from "../../modes/components/extensions/state-manag
 import { theme } from "../../modes/theme/theme";
 import { type PlanApprovalDetails, resolveApprovedPlan } from "../../plan-mode/approved-plan";
 import type { AgentSession, AgentSessionEvent } from "../../session/agent-session";
+import { BlobStore, resolveImageDataSync } from "../../session/blob-store";
 import { isSilentAbort, SKILL_PROMPT_MESSAGE_TYPE, USER_INTERRUPT_LABEL } from "../../session/messages";
 import type { UsageStatistics } from "../../session/session-entries";
 import type { SessionInfo as StoredSessionInfo } from "../../session/session-listing";
@@ -445,6 +446,7 @@ export class AcpAgent implements Agent {
 	#cleanupRegistered = false;
 	#clientCapabilities: ClientCapabilities | undefined;
 	#cancelCleanupTimeoutMs = ACP_CANCEL_CLEANUP_TIMEOUT_MS;
+	#blobs = new BlobStore(getBlobsDir());
 
 	constructor(connection: AgentSideConnection, createSession: CreateAcpSession, initialSession?: AgentSession) {
 		this.#connection = connection;
@@ -1187,11 +1189,21 @@ export class AcpAgent implements Agent {
 		}
 
 		this.#prepareLiveAssistantMessage(record, event);
+		const imageDataCache = new Map<string, string>();
+		const resolveImageDataForAcp = (data: string, mimeType: string | undefined): string => {
+			const key = `${mimeType ?? ""}\u0000${data}`;
+			const cached = imageDataCache.get(key);
+			if (cached !== undefined) return cached;
+			const resolved = resolveImageDataSync(this.#blobs, data);
+			imageDataCache.set(key, resolved);
+			return resolved;
+		};
 		for (const notification of mapAgentSessionEventToAcpSessionUpdates(event, record.session.sessionId, {
 			getMessageId: message => this.#getLiveMessageId(record, message),
 			getMessageProgress: message => this.#getLiveMessageProgress(record, message),
 			getToolArgs: toolCallId => record.toolArgsById.get(toolCallId),
 			cwd: record.session.sessionManager.getCwd(),
+			resolveImageData: resolveImageDataForAcp,
 		})) {
 			await this.#connection.sessionUpdate(notification);
 		}
@@ -2052,6 +2064,7 @@ export class AcpAgent implements Agent {
 		const notifications = mapAgentSessionEventToAcpSessionUpdates(endEvent, sessionId, {
 			cwd,
 			getToolArgs: toolCallId => (toolCallId === message.toolCallId ? options.toolArgs : undefined),
+			resolveImageData: (data, _mimeType) => resolveImageDataSync(this.#blobs, data),
 		});
 		if (options.includeStart === false) {
 			return notifications;

package/src/modes/acp/acp-event-mapper.ts

@@ -20,6 +20,7 @@ interface AcpEventMapperOptions {
 	getMessageId?: (message: unknown) => string | undefined;
 	getMessageProgress?: (message: unknown) => MessageProgress | undefined;
 	getToolArgs?: (toolCallId: string) => unknown;
+	resolveImageData?: (data: string, mimeType: string | undefined) => string;
 	/**
 	 * Session cwd. Tool call locations sent to ACP clients must be absolute
 	 * (the editor host needs them to open or focus files). When provided,
@@ -143,8 +144,8 @@ export function mapToolKind(toolName: string): ToolKind {
 		case "exec":
 		case "eval":
 			return "execute";
-		case "search":
-		case "find":
+		case "grep":
+		case "glob":
 		case "ast_grep":
 			return "search";
 		case "web_search":
@@ -179,7 +180,7 @@ export function mapAgentSessionEventToAcpSessionUpdates(
 		case "tool_execution_update": {
 			const content = mergeToolUpdateContent(
 				buildToolStartContent(event.toolName, event.args),
-				extractToolCallContent(event.partialResult),
+				extractToolCallContent(event.partialResult, options),
 			);
 			const update: SessionUpdate = {
 				sessionUpdate: "tool_call_update",
@@ -197,7 +198,10 @@ export function mapAgentSessionEventToAcpSessionUpdates(
 			return [toSessionNotification(sessionId, update)];
 		}
 		case "tool_execution_end": {
-			const resultContent = [...extractDiffToolCallContent(event.result), ...extractToolCallContent(event.result)];
+			const resultContent = [
+				...extractDiffToolCallContent(event.result),
+				...extractToolCallContent(event.result, options),
+			];
 			const content = mergeToolUpdateContent(
 				buildToolStartContent(event.toolName, getToolExecutionEndArgs(event, options)),
 				resultContent,
@@ -641,13 +645,15 @@ function terminalToolCallContent(terminalId: string): ToolCallContent {
 	return { type: "terminal", terminalId };
 }
 
-function extractToolCallContent(value: unknown): ToolCallContent[] {
-	const richContent = extractStructuredToolCallContent(value);
+function extractToolCallContent(value: unknown, options: AcpEventMapperOptions): ToolCallContent[] {
+	const richContent = extractStructuredToolCallContent(value, options);
+	const detailsImageContent = extractDetailsImageToolCallContent(value, options, richContent);
+	const combinedContent = [...richContent, ...detailsImageContent];
 	const terminalId = extractTerminalId(value);
 	const content =
-		terminalId && !hasTerminalContent(richContent, terminalId)
-			? [...richContent, terminalToolCallContent(terminalId)]
-			: richContent;
+		terminalId && !hasTerminalContent(combinedContent, terminalId)
+			? [...combinedContent, terminalToolCallContent(terminalId)]
+			: combinedContent;
 	const fallbackText = extractReadableText(value);
 	if (!fallbackText) {
 		return content;
@@ -658,7 +664,7 @@ function extractToolCallContent(value: unknown): ToolCallContent[] {
 	return [...content, textToolCallContent(fallbackText)];
 }
 
-function extractStructuredToolCallContent(value: unknown): ToolCallContent[] {
+function extractStructuredToolCallContent(value: unknown, options: AcpEventMapperOptions): ToolCallContent[] {
 	const blocks = getContentBlocks(value);
 	if (!blocks) {
 		return [];
@@ -666,7 +672,7 @@ function extractStructuredToolCallContent(value: unknown): ToolCallContent[] {
 
 	const content: ToolCallContent[] = [];
 	for (const block of blocks) {
-		const toolCallContent = toToolCallContent(block);
+		const toolCallContent = toToolCallContent(block, options);
 		if (toolCallContent) {
 			content.push(toolCallContent);
 		}
@@ -685,7 +691,7 @@ function getContentBlocks(value: unknown): unknown[] | undefined {
 	return Array.isArray(content) ? content : undefined;
 }
 
-function toToolCallContent(value: unknown): ToolCallContent | undefined {
+function toToolCallContent(value: unknown, options: AcpEventMapperOptions): ToolCallContent | undefined {
 	const type = getContentType(value);
 	if (!type) {
 		return undefined;
@@ -697,21 +703,8 @@ function toToolCallContent(value: unknown): ToolCallContent | undefined {
 			return text ? textToolCallContent(text) : undefined;
 		}
 		case "image":
-		case "audio": {
-			const data = extractStringProperty<BinaryLikeContent>(value, "data");
-			const mimeType = extractStringProperty<BinaryLikeContent>(value, "mimeType");
-			if (!data || !mimeType) {
-				return undefined;
-			}
-			return {
-				type: "content",
-				content: {
-					type,
-					data,
-					mimeType,
-				},
-			};
-		}
+		case "audio":
+			return binaryToolCallContent(type, value, options);
 		case "resource_link": {
 			const uri = extractStringProperty<ResourceLinkLikeContent>(value, "uri");
 			const name = extractStringProperty<ResourceLinkLikeContent>(value, "name");
@@ -769,6 +762,64 @@ function toToolCallContent(value: unknown): ToolCallContent | undefined {
 	}
 }
 
+function binaryToolCallContent(
+	type: "image" | "audio",
+	value: unknown,
+	options: AcpEventMapperOptions,
+): ToolCallContent | undefined {
+	const data = extractStringProperty<BinaryLikeContent>(value, "data");
+	const mimeType = extractStringProperty<BinaryLikeContent>(value, "mimeType");
+	if (!data || !mimeType) {
+		return undefined;
+	}
+	return {
+		type: "content",
+		content: {
+			type,
+			data: type === "image" ? (options.resolveImageData?.(data, mimeType) ?? data) : data,
+			mimeType,
+		},
+	};
+}
+
+function extractDetailsImageToolCallContent(
+	value: unknown,
+	options: AcpEventMapperOptions,
+	existing: ToolCallContent[],
+): ToolCallContent[] {
+	const images = extractDetailsImages(value);
+	if (!images) {
+		return [];
+	}
+	const seen = new Set(existing.map(imageContentKey).filter((key): key is string => key !== undefined));
+	const content: ToolCallContent[] = [];
+	for (const image of images) {
+		const toolCallContent = binaryToolCallContent("image", image, options);
+		const key = imageContentKey(toolCallContent);
+		if (!toolCallContent || !key || seen.has(key)) {
+			continue;
+		}
+		seen.add(key);
+		content.push(toolCallContent);
+	}
+	return content;
+}
+
+function extractDetailsImages(value: unknown): unknown[] | undefined {
+	if (typeof value !== "object" || value === null) return undefined;
+	const details = (value as DetailsContainer).details;
+	if (typeof details !== "object" || details === null) return undefined;
+	const images = (details as { images?: unknown }).images;
+	return Array.isArray(images) && images.length > 0 ? images : undefined;
+}
+
+function imageContentKey(value: ToolCallContent | undefined): string | undefined {
+	if (value?.type !== "content" || value.content.type !== "image") {
+		return undefined;
+	}
+	return `${value.content.mimeType}\u0000${value.content.data}`;
+}
+
 function extractEmbeddedResource(
 	value: unknown,
 ): { uri: string; text: string; mimeType?: string } | { uri: string; blob: string; mimeType?: string } | undefined {
@@ -846,6 +897,12 @@ function extractReadableText(value: unknown): string | undefined {
 		if (text.length > 0) {
 			return normalizeText(text);
 		}
+		if (hasBinaryContentBlock(contentBlocks)) {
+			return undefined;
+		}
+	}
+	if (extractDetailsImages(value)) {
+		return undefined;
 	}
 	if (isTerminalOnlyDetails(value)) {
 		return undefined;
@@ -895,6 +952,13 @@ function getContentType(value: unknown): string | undefined {
 	return typeof type === "string" ? type : undefined;
 }
 
+function hasBinaryContentBlock(blocks: unknown[]): boolean {
+	return blocks.some(block => {
+		const type = getContentType(block);
+		return type === "image" || type === "audio";
+	});
+}
+
 function extractStringProperty<T extends object>(value: unknown, key: keyof T): string | undefined {
 	if (typeof value !== "object" || value === null || !(key in value)) {
 		return undefined;

package/src/modes/components/__tests__/move-overlay.test.ts

@@ -0,0 +1,166 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, it } from "bun:test";
+import * as fs from "node:fs";
+import * as fsp from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { Settings } from "../../../config/settings";
+import { getThemeByName, setThemeInstance, type Theme } from "../../theme/theme";
+import { MoveOverlay, type MoveOverlayResult, resolveExistingDirectory, resolveMovePath } from "../move-overlay";
+
+// Strip SGR colors so assertions see visible text only.
+const strip = (lines: readonly string[]): string => lines.join("\n").replace(/\x1b\[[0-9;]*m/g, "");
+
+describe("resolveMovePath", () => {
+	it("expands ~ to homedir", () => {
+		expect(resolveMovePath("~", "/anywhere")).toBe(os.homedir());
+	});
+	it("expands ~/sub to homedir/sub", () => {
+		expect(resolveMovePath("~/foo", "/anywhere")).toBe(path.join(os.homedir(), "foo"));
+	});
+	it("resolves relative paths against cwd", () => {
+		expect(resolveMovePath("foo/bar", "/parent")).toBe(path.resolve("/parent", "foo/bar"));
+	});
+	it("passes absolute paths through (normalized)", () => {
+		expect(resolveMovePath("/abs/path", "/anywhere")).toBe(path.normalize("/abs/path"));
+	});
+});
+
+describe("resolveExistingDirectory", () => {
+	let tmp: string;
+
+	beforeEach(async () => {
+		tmp = await fsp.mkdtemp(path.join(os.tmpdir(), "omp-move-resolve-"));
+	});
+	afterEach(async () => {
+		await fsp.rm(tmp, { recursive: true, force: true });
+	});
+
+	it("returns the resolved path for an existing directory", () => {
+		const sub = path.join(tmp, "sub");
+		fs.mkdirSync(sub);
+		expect(resolveExistingDirectory(sub, "/anywhere")).toBe(path.resolve(sub));
+	});
+	it("returns null for a non-existent path", () => {
+		expect(resolveExistingDirectory(path.join(tmp, "nope"), "/anywhere")).toBeNull();
+	});
+	it("returns null for a file (not a directory)", () => {
+		const file = path.join(tmp, "file.txt");
+		fs.writeFileSync(file, "x");
+		expect(resolveExistingDirectory(file, "/anywhere")).toBeNull();
+	});
+});
+
+describe("MoveOverlay", () => {
+	let tmp: string;
+	let cwd: string;
+	let uiTheme: Theme;
+
+	beforeAll(async () => {
+		await Settings.init({ inMemory: true });
+		const loaded = await getThemeByName("dark");
+		if (!loaded) throw new Error("theme unavailable");
+		uiTheme = loaded;
+		setThemeInstance(uiTheme);
+	});
+
+	beforeEach(async () => {
+		tmp = await fsp.mkdtemp(path.join(os.tmpdir(), "omp-move-overlay-"));
+		cwd = tmp;
+		fs.mkdirSync(path.join(tmp, "alpha"));
+		fs.mkdirSync(path.join(tmp, "beta"));
+		fs.mkdirSync(path.join(tmp, ".hidden"));
+		fs.writeFileSync(path.join(tmp, "file.txt"), "x");
+	});
+	afterEach(async () => {
+		await fsp.rm(tmp, { recursive: true, force: true });
+	});
+
+	it("renders a box with a title and input prompt", () => {
+		const overlay = new MoveOverlay(cwd, () => {});
+		const text = strip(overlay.render(80));
+		expect(text).toContain("Move to directory");
+		expect(text).toContain("Path:");
+	});
+
+	it("lists child directories (excluding hidden and files) on empty input", () => {
+		const overlay = new MoveOverlay(cwd, () => {});
+		const text = strip(overlay.render(80));
+		expect(text).toContain("alpha/");
+		expect(text).toContain("beta/");
+		expect(text).not.toContain(".hidden/");
+		expect(text).not.toContain("file.txt");
+	});
+
+	it("filters results as the user types", () => {
+		const overlay = new MoveOverlay(cwd, () => {});
+		overlay.handleInput("a");
+		overlay.handleInput("l");
+		const text = strip(overlay.render(80));
+		expect(text).toContain("alpha/");
+		expect(text).not.toContain("beta/");
+	});
+
+	it("shows dot directories after a dot prefix is typed", () => {
+		const overlay = new MoveOverlay(cwd, () => {});
+		overlay.handleInput(".");
+		const text = strip(overlay.render(80));
+		expect(text).toContain(".hidden/");
+	});
+
+	it("accepts bracketed paste and multi-byte input while filtering controls", () => {
+		let result: MoveOverlayResult | undefined;
+		const overlay = new MoveOverlay(cwd, r => {
+			result = r;
+		});
+		overlay.handleInput("\x1b[200~new\nø\x1b[201~");
+		overlay.handleInput("\r");
+		expect(result).toBeDefined();
+		expect(result!.directory).toBe("newø");
+	});
+
+	it("calls done with undefined on Escape", () => {
+		let result: MoveOverlayResult | undefined = "sentinel" as unknown as MoveOverlayResult;
+		const overlay = new MoveOverlay(cwd, r => {
+			result = r;
+		});
+		overlay.handleInput("\x1b");
+		expect(result).toBeUndefined();
+	});
+
+	it("calls done with the highlighted directory on Enter", () => {
+		let result: MoveOverlayResult | undefined;
+		const overlay = new MoveOverlay(cwd, r => {
+			result = r;
+		});
+		// First result should be "alpha/" (sorted alphabetically).
+		overlay.handleInput("\r");
+		expect(result).toBeDefined();
+		expect(result!.directory).toBe(path.join(cwd, "alpha"));
+	});
+
+	it("calls done with the typed path on Enter when no results match", () => {
+		let result: MoveOverlayResult | undefined;
+		const overlay = new MoveOverlay(cwd, r => {
+			result = r;
+		});
+		// Type a path that won't match any directory in cwd.
+		overlay.handleInput("z");
+		overlay.handleInput("z");
+		overlay.handleInput("\r");
+		expect(result).toBeDefined();
+		expect(result!.directory).toBe("zz");
+	});
+
+	it("Tab accepts the highlighted suggestion into the input", () => {
+		let result: MoveOverlayResult | undefined;
+		const overlay = new MoveOverlay(cwd, r => {
+			result = r;
+		});
+		overlay.handleInput("\t");
+		// After tab, the input should be the full path of the first result.
+		// Press Enter to confirm — the result should be the alpha directory.
+		overlay.handleInput("\r");
+		expect(result).toBeDefined();
+		expect(result!.directory).toBe(path.join(cwd, "alpha"));
+	});
+});

package/src/modes/components/agent-hub.ts

@@ -425,6 +425,9 @@ export class AgentHubOverlayComponent extends Container {
 		const parts: string[] = [statusBadge(ref.status), theme.bold(replaceTabs(ref.id))];
 		parts.push(theme.fg("dim", replaceTabs(ref.displayName)));
 		parts.push(theme.fg("dim", ref.parentId ? `${ref.kind} · of ${ref.parentId}` : ref.kind));
+		if (ref.kind === "advisor") {
+			parts.push(theme.fg("warning", "read-only"));
+		}
 		const observed = this.#observableFor(ref.id);
 		const task = observed?.description ?? observed?.progress?.task;
 		if (task) {

package/src/modes/components/agent-transcript-viewer.ts

@@ -15,7 +15,7 @@
  */
 import * as fs from "node:fs";
 import type { AgentTool } from "@oh-my-pi/pi-agent-core";
-import { type Component, Editor, matchesKey, parseSgrMouse, ScrollView, type TUI } from "@oh-my-pi/pi-tui";
+import { type Component, Editor, matchesKey, routeSgrMouseInput, ScrollView, type TUI } from "@oh-my-pi/pi-tui";
 import { formatDuration, formatNumber, logger } from "@oh-my-pi/pi-utils";
 import type { KeyId } from "../../config/keybindings";
 import type { MessageRenderer } from "../../extensibility/extensions/types";
@@ -413,12 +413,14 @@ export class AgentTranscriptViewer implements Component {
 
 	handleInput(data: string): void {
 		if (data.startsWith("\x1b[<")) {
-			const event = parseSgrMouse(data);
-			if (event?.wheel != null) {
-				this.#scrollView.scroll(event.wheel * 3);
-				this.#syncFollow();
-				this.deps.requestRender();
-			}
+			routeSgrMouseInput(data, event => {
+				if (event.wheel !== null) {
+					this.#scrollView.scroll(event.wheel * 3);
+					this.#syncFollow();
+					this.deps.requestRender();
+				}
+				return true;
+			});
 			return;
 		}
 

package/src/modes/components/custom-editor.ts

@@ -1,6 +1,7 @@
 import { fileURLToPath } from "node:url";
 import type { ImageContent } from "@oh-my-pi/pi-ai";
 import { addKeyAliases, canonicalKeyId, Editor, type KeyId, parseKey, parseKittySequence } from "@oh-my-pi/pi-tui";
+import { BracketedPasteHandler } from "@oh-my-pi/pi-tui/bracketed-paste";
 import type { AppKeybinding } from "../../config/keybindings";
 import { isSettingsInitialized, settings } from "../../config/settings";
 import { imageReferenceHyperlink, PLACEHOLDER_REGEX, renderPlaceholders } from "../image-references";
@@ -229,6 +230,17 @@ export function extractBracketedImagePastePaths(data: string): string[] | undefi
 	return paths?.every(isImagePath) ? paths : undefined;
 }
 
+/**
+ * Same shape as {@link extractBracketedImagePastePaths} but operates on a
+ * payload that has already been stripped of the `\x1b[200~` / `\x1b[201~`
+ * markers — used by the assembled-paste router in {@link CustomEditor.handleInput}
+ * so split bracketed pastes get the same image-path detection as single-chunk ones.
+ */
+export function extractImagePastePathsFromText(text: string): string[] | undefined {
+	const paths = extractPastePathsFromText(text);
+	return paths?.every(isImagePath) ? paths : undefined;
+}
+
 export function extractBracketedImagePastePath(data: string): string | undefined {
 	const paths = extractBracketedImagePastePaths(data);
 	return paths?.length === 1 ? paths[0] : undefined;
@@ -422,6 +434,19 @@ export class CustomEditor extends Editor {
 	/** Custom key handlers from extensions and non-built-in app actions. */
 	#customKeyHandlers = new Map<KeyId, () => void>();
 	#customMatchKeys = new Map<string, () => void>();
+	/** Bracketed-paste assembler that runs ahead of the inherited handler so terminals which
+	 *  deliver `\x1b[200~` and `\x1b[201~` in separate stdin chunks still resolve to a single
+	 *  assembled payload here; the empty-paste / image-path branches must see the full content,
+	 *  not the raw single-chunk byte sequence. */
+	#pasteHandler = new BracketedPasteHandler();
+	/** Number of async pastes (clipboard-image reads / image-path attachments) currently in flight.
+	 *  While > 0, `handleInput` queues subsequent keystrokes into {@link #pendingInput} instead of
+	 *  dispatching them so a trailing `Enter` after `Cmd+V` can't submit before the image lands on
+	 *  `pendingImages` (Codex PR #3602 review). */
+	#pasteInFlight = 0;
+	/** Input chunks deferred behind an in-flight paste, drained in FIFO order once the paste
+	 *  count returns to zero. */
+	#pendingInput: string[] = [];
 	/** Spaces actually inserted in the current run; tracked back out when a hold is recognized. */
 	#spaceRunInserted = 0;
 	/** Consecutive "mechanical" deltas (fast + steady); a sustained run of these confirms a held bar. */
@@ -575,7 +600,34 @@ export class CustomEditor extends Editor {
 		this.onSpaceHoldEnd?.();
 	}
 
+	/** Decrement {@link #pasteInFlight} once an async paste settles and, when the count returns
+	 *  to zero, drain {@link #pendingInput} through `handleInput` so requeueing still works if a
+	 *  drained chunk triggers another async paste. Bound member so it can be passed straight to
+	 *  `Promise.then(callback, callback)`. */
+	#onPasteSettled = (): void => {
+		this.#pasteInFlight--;
+		if (this.#pasteInFlight > 0) return;
+		const drained = this.#pendingInput.splice(0);
+		for (const chunk of drained) this.handleInput(chunk);
+	};
+
+	/** Track `promise` as an in-flight paste so subsequent `handleInput` calls queue behind it,
+	 *  then drain the queue once it settles. Codex PR #3602 review: without this, a trailing
+	 *  keystroke (Enter most painfully) in the same stdin read processes synchronously while the
+	 *  clipboard read is still pending — submit fires with the text but `pendingImages` is still
+	 *  empty and the image lands on the *next* draft instead. */
+	#trackAsyncPaste(promise: Promise<unknown>): void {
+		this.#pasteInFlight++;
+		void promise.then(this.#onPasteSettled, this.#onPasteSettled);
+	}
+
 	handleInput(data: string): void {
+		// Serialize behind any in-flight async paste so a trailing Enter / follow-up key can't
+		// submit before the clipboard image reaches `pendingImages` (Codex PR #3602 review).
+		if (this.#pasteInFlight > 0) {
+			this.#pendingInput.push(data);
+			return;
+		}
 		const kittyParsed = parseKittySequence(data);
 		if (kittyParsed && (kittyParsed.modifier & 64) !== 0 && this.onCapsLock) {
 			// Caps Lock is modifier bit 64
@@ -583,11 +635,44 @@ export class CustomEditor extends Editor {
 			return;
 		}
 
-		const pastedImagePaths = extractBracketedImagePastePaths(data);
-		if (pastedImagePaths && this.onPasteImagePath) {
-			void (async () => {
-				for (const path of pastedImagePaths) await this.onPasteImagePath?.(path);
-			})();
+		// Bracketed-paste assembly. Some terminals fragment the start marker,
+		// the payload, and the end marker across separate stdin chunks
+		// (Windows Terminal under heavy load, certain SSH muxes, …); the
+		// inherited handler then sees a zero-length payload and silently
+		// drops it through the normal text-insert path. Running our own
+		// `BracketedPasteHandler` ahead of `super.handleInput` lets us route
+		// the assembled content regardless of chunk boundaries:
+		//  - empty payload → `onPasteImage` (#3601: `Cmd+V`/`Ctrl+V` on an
+		//    image-only macOS pasteboard the terminal stripped to `""` first);
+		//  - explicit image-file paths → `onPasteImagePath` (#3506);
+		//  - anything else → the base editor's `pasteText` so `[Paste #N]`
+		//    markers, autocomplete, and undo state stay intact.
+		const paste = this.#pasteHandler.process(data);
+		if (paste.handled) {
+			if (paste.pasteContent === undefined) return; // still buffering — wait for end marker
+			const content = paste.pasteContent;
+			const remaining = paste.remaining;
+			// Queue any trailing bytes from the same read (typically a follow-up keystroke such as
+			// Enter that the user pressed right after Cmd+V) so they only fire *after* the paste
+			// completes — fixes the race where submit runs against an empty `pendingImages`.
+			if (remaining.length > 0) this.#pendingInput.push(remaining);
+			if (content.length === 0 && this.onPasteImage) {
+				this.#trackAsyncPaste(Promise.resolve(this.onPasteImage()));
+				return;
+			}
+			const imagePaths = extractImagePastePathsFromText(content);
+			if (imagePaths && this.onPasteImagePath) {
+				this.#trackAsyncPaste(
+					(async () => {
+						for (const p of imagePaths) await this.onPasteImagePath?.(p);
+					})(),
+				);
+				return;
+			}
+			this.pasteText(content);
+			// No async paste was started; drain the queued trailing bytes ourselves.
+			const drained = this.#pendingInput.splice(0);
+			for (const chunk of drained) this.handleInput(chunk);
 			return;
 		}