@oh-my-pi/pi-coding-agent 16.1.22 → 16.2.0

package/src/mcp/tool-bridge.ts

@@ -7,6 +7,7 @@ import type { AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import type { TSchema } from "@oh-my-pi/pi-ai";
 import { normalizeSchemaForMCP } from "@oh-my-pi/pi-ai/utils/schema";
 import { untilAborted } from "@oh-my-pi/pi-utils";
+import { INTENT_FIELD } from "@oh-my-pi/pi-wire";
 import type { SourceMeta } from "../capability/types";
 import type {
 	CustomTool,
@@ -83,6 +84,35 @@ function omitUnusedOptionalArgs(args: MCPToolArgs, inputSchema: MCPToolDefinitio
 	return cleaned ?? args;
 }
 
+/**
+ * Drop the harness-internal intent field (`INTENT_FIELD`) before forwarding
+ * args to an MCP server. The harness injects `i` into every tool's wire
+ * schema; the direct model tool-call path strips it via `extractIntent`, but
+ * the `eval` `tool.*` bridge and any other in-process caller forwards args
+ * verbatim. Strict-schema servers (Linear, anything with
+ * `additionalProperties:false` / Zod `.strict()`) reject every call that
+ * carries `i`. The MCP boundary is the authoritative guard so callers don't
+ * have to pre-strip.
+ *
+ * Leaves `i` in place when the server's own `inputSchema.properties` declares
+ * it, so a server that legitimately uses `i` as a parameter is unaffected.
+ */
+function stripHarnessIntent(args: MCPToolArgs, inputSchema: MCPToolDefinition["inputSchema"]): MCPToolArgs {
+	if (!Object.hasOwn(args, INTENT_FIELD)) return args;
+	if (inputSchema.properties && Object.hasOwn(inputSchema.properties, INTENT_FIELD)) return args;
+	const { [INTENT_FIELD]: _intent, ...rest } = args;
+	return rest;
+}
+
+/**
+ * Normalize raw tool params into the outbound `tools/call` arguments: strip
+ * the harness intent field, then drop optional empty placeholders the server
+ * declares but doesn't require.
+ */
+function prepareOutboundArgs(params: unknown, inputSchema: MCPToolDefinition["inputSchema"]): MCPToolArgs {
+	return omitUnusedOptionalArgs(stripHarnessIntent(normalizeToolArgs(params), inputSchema), inputSchema);
+}
+
 /** Details included in MCP tool results for rendering */
 export interface MCPToolDetails {
 	/** Server name */
@@ -286,7 +316,7 @@ export class MCPTool implements CustomTool<TSchema, MCPToolDetails> {
 		signal?: AbortSignal,
 	): Promise<CustomToolResult<MCPToolDetails>> {
 		throwIfAborted(signal);
-		const args = omitUnusedOptionalArgs(normalizeToolArgs(params), this.tool.inputSchema);
+		const args = prepareOutboundArgs(params, this.tool.inputSchema);
 		const provider = this.connection._source?.provider;
 		const providerName = this.connection._source?.providerName;
 
@@ -385,7 +415,7 @@ export class DeferredMCPTool implements CustomTool<TSchema, MCPToolDetails> {
 		signal?: AbortSignal,
 	): Promise<CustomToolResult<MCPToolDetails>> {
 		throwIfAborted(signal);
-		const args = omitUnusedOptionalArgs(normalizeToolArgs(params), this.tool.inputSchema);
+		const args = prepareOutboundArgs(params, this.tool.inputSchema);
 		const provider = this.#fallbackProvider;
 		const providerName = this.#fallbackProviderName;
 

package/src/mcp/transports/stdio.test.ts

@@ -3,19 +3,35 @@ import { describe, expect, it } from "bun:test";
 import { resolveStdioSpawnCommand } from "./stdio";
 
 describe("resolveStdioSpawnCommand", () => {
-	it("hides direct Windows executable MCP servers", async () => {
+	it("hides Windows executable MCP servers when the host has no console", async () => {
+		// Hidden so a console-app child does not allocate a visible window when
+		// OMP is launched without a terminal console (#3536).
 		await expect(
 			resolveStdioSpawnCommand(
 				{ command: "server.exe", args: ["--stdio"] },
-				{ cwd: process.cwd(), env: {}, platform: "win32" },
+				{ cwd: process.cwd(), env: {}, platform: "win32", hostHasInheritableConsole: false },
 			),
 		).resolves.toEqual({
 			cmd: ["server.exe", "--stdio"],
 			windowsHide: true,
+			detached: false,
 		});
 	});
 
-	it("keeps off-Windows spawn options unchanged", async () => {
+	it("inherits an attached Windows console instead of forcing CREATE_NO_WINDOW", async () => {
+		await expect(
+			resolveStdioSpawnCommand(
+				{ command: "server.exe", args: ["--stdio"] },
+				{ cwd: process.cwd(), env: {}, platform: "win32", hostHasInheritableConsole: true },
+			),
+		).resolves.toEqual({
+			cmd: ["server.exe", "--stdio"],
+			windowsHide: false,
+			detached: false,
+		});
+	});
+
+	it("detaches off-Windows MCP servers so terminal job-control signals cannot stop them", async () => {
 		await expect(
 			resolveStdioSpawnCommand(
 				{ command: "server.exe", args: ["--stdio"] },
@@ -23,6 +39,7 @@ describe("resolveStdioSpawnCommand", () => {
 			),
 		).resolves.toEqual({
 			cmd: ["server.exe", "--stdio"],
+			detached: true,
 		});
 	});
 });

package/src/mcp/transports/stdio.ts

@@ -7,9 +7,9 @@
 
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-
 import { getProjectDir, readJsonl, Snowflake } from "@oh-my-pi/pi-utils";
 import { type Subprocess, spawn } from "bun";
+import { hostHasInheritableConsole } from "../../eval/py/spawn-options";
 import type {
 	JsonRpcError,
 	JsonRpcMessage,
@@ -22,16 +22,40 @@ import type {
 import { toJsonRpcError } from "../../mcp/types";
 import { isMCPTimeoutEnabled, resolveMCPTimeoutMs } from "../timeout";
 
-/** Subprocess argv for launching an MCP stdio server. */
+/** Subprocess argv and platform-derived spawn flags for an MCP stdio server. */
 export interface StdioSpawnCommand {
 	cmd: string[];
+	/**
+	 * Hide the Windows console window for the direct child.
+	 *
+	 * Windows uses this only when the OMP host has no console to share. When
+	 * the host is running inside a terminal, `windowsHide: true` maps to
+	 * `CREATE_NO_WINDOW`, which strips that inheritable console from hidden
+	 * `cmd.exe` / PowerShell wrapper chains. Their console grandchildren then
+	 * allocate fresh visible conhost windows during startup or reconnects
+	 * (#3567).
+	 */
 	windowsHide?: boolean;
+	/**
+	 * Run the subprocess in its own session.
+	 *
+	 * POSIX: `true`. Detach → `setsid`, so the MCP process tree has no
+	 * controlling terminal and terminal job-control signals (Ctrl+Z SIGTSTP,
+	 * background-read SIGTTIN) cannot stop stdio servers such as
+	 * `chrome-devtools-mcp` and leave our read loop blocked on silent pipes.
+	 *
+	 * Windows: `false`. There is no SIGTSTP/SIGTTIN to escape, and Windows
+	 * wrapper chains must stay in the OMP console session so nested console
+	 * grandchildren keep stdout routed through our pipe (#3544).
+	 */
+	detached: boolean;
 }
 
 /** Inputs used to resolve platform-specific stdio spawn behavior. */
 export interface ResolveStdioSpawnOptions {
 	cwd: string;
 	env: Record<string, string | undefined>;
+	hostHasInheritableConsole?: boolean;
 	platform?: NodeJS.Platform;
 }
 
@@ -142,6 +166,7 @@ async function resolveWindowsNpmShimCommand(
 	command: string,
 	args: readonly string[],
 	cwd: string,
+	windowsHide: boolean,
 ): Promise<StdioSpawnCommand | null> {
 	if (!isWindowsBatchCommand(command)) return null;
 	if (!hasPathSegment(command)) return null;
@@ -176,7 +201,8 @@ async function resolveWindowsNpmShimCommand(
 	const nodeCommand = (await fileExists(siblingNode)) ? siblingNode : "node";
 	return {
 		cmd: [nodeCommand, target, ...args],
-		windowsHide: true,
+		windowsHide,
+		detached: false,
 	};
 }
 
@@ -229,25 +255,28 @@ export async function resolveStdioSpawnCommand(
 	options: ResolveStdioSpawnOptions,
 ): Promise<StdioSpawnCommand> {
 	const args = config.args ?? [];
-	if (options.platform !== "win32") return { cmd: [config.command, ...args] };
+	if (options.platform !== "win32") return { cmd: [config.command, ...args], detached: true };
 
+	const windowsHide = options.hostHasInheritableConsole === undefined ? true : !options.hostHasInheritableConsole;
 	const resolved = await resolveWindowsCommandPath(config.command, options.cwd, options.env);
 	const resolvedCommand = resolved ?? config.command;
-	const npmShimCommand = await resolveWindowsNpmShimCommand(resolvedCommand, args, options.cwd);
+	const npmShimCommand = await resolveWindowsNpmShimCommand(resolvedCommand, args, options.cwd, windowsHide);
 	if (npmShimCommand) return npmShimCommand;
 
 	// Direct-spawn only when we resolved to a concrete file AND its extension
 	// is not a batch script. Everything else (resolved .cmd/.bat, or an
 	// unresolved extensionless command) goes through cmd.exe so PATHEXT runs.
-	// Every Windows stdio server launch hides its console window; otherwise
-	// direct .exe servers pop a visible cmd window while the MCP server lives.
-	const windowsHide = true;
+	// Windows stdio servers stay attached so wrapper grandchildren inherit the
+	// same console session. Only hide the child when OMP itself has no console
+	// to share; CREATE_NO_WINDOW breaks console inheritance for nested wrappers.
+	const detached = false;
 	const needsCmdExe = resolved === null || isWindowsBatchCommand(resolvedCommand);
-	if (!needsCmdExe) return { cmd: [resolvedCommand, ...args], windowsHide };
+	if (!needsCmdExe) return { cmd: [resolvedCommand, ...args], windowsHide, detached };
 
 	return {
 		cmd: [resolveComSpec(options.env), "/d", "/s", "/c", buildCmdExeCommand(resolvedCommand, args)],
 		windowsHide,
+		detached,
 	};
 }
 
@@ -341,12 +370,14 @@ export class StdioTransport implements MCPTransport {
 			cwd,
 			env,
 			platform: process.platform,
+			hostHasInheritableConsole: hostHasInheritableConsole(),
 		});
 
-		// Spawn in a new session (detached → setsid) so the MCP process tree has
-		// no controlling terminal. Otherwise terminal job-control signals (Ctrl+Z
-		// SIGTSTP, background-read SIGTTIN) can stop stdio servers such as
-		// chrome-devtools-mcp and leave our read loop blocked on silent pipes.
+		// Platform-derived session and console-window handling come from
+		// `resolveStdioSpawnCommand`: POSIX detaches into its own session to
+		// escape terminal job-control signals (SIGTSTP, SIGTTIN); Windows stays
+		// attached, and only hides the child when the host has no console to
+		// share. See `StdioSpawnCommand`.
 		this.#process = spawn({
 			cmd: spawnCommand.cmd,
 			cwd,
@@ -355,7 +386,7 @@ export class StdioTransport implements MCPTransport {
 			stdout: "pipe",
 			stderr: "pipe",
 			windowsHide: spawnCommand.windowsHide,
-			detached: true,
+			detached: spawnCommand.detached,
 		});
 
 		this.#connected = true;

package/src/memories/index.ts

@@ -559,7 +559,7 @@ function shouldPersistResponseItemForMemories(message: AgentMessage): boolean {
 	}
 	if (role !== "toolResult") return false;
 	const toolName = (message as { toolName?: string }).toolName;
-	if (toolName === "bash" || toolName === "eval" || toolName === "read" || toolName === "search") {
+	if (toolName === "bash" || toolName === "eval" || toolName === "read" || toolName === "grep") {
 		const text = extractMessageText(message);
 		return text.length > 0 && text.length <= 32_000;
 	}

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

@@ -143,8 +143,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":

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