@gajae-code/coding-agent 0.10.1 → 0.10.2

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

@@ -248,6 +248,7 @@ export class CustomEditor extends Editor {
 			const paste = this.#pasteHandler.process(data);
 			if (paste.handled) {
 				if (paste.pasteContent !== undefined) {
+					this.onViewportFollowLive?.();
 					this.#handleBracketedPaste(paste.pasteContent, paste.remaining);
 				}
 				return;

package/src/modes/components/gajae-pet-widget.ts

@@ -6,7 +6,6 @@ import {
 	type GajaePixelFrameName,
 	type GajaePixelFrames,
 	getCellDimensions,
-	ImageProtocol,
 	PARA_PARA_STEPS,
 	PET_SKINS,
 	type PetMode,
@@ -14,10 +13,10 @@ import {
 	petBurstDurationMs,
 	petBurstFrame,
 	registerAnimationCallback,
-	TERMINAL,
 	type TUI,
 } from "@gajae-code/tui";
 import type { CustomEditor } from "./custom-editor";
+import { getPetPixelProtocol } from "./pet-capability";
 
 /** Re-exported from the tui skin registry so widget-relative imports stay valid. */
 export type { PetMode, PetSkinId };
@@ -38,6 +37,35 @@ const KITTY_DROP_FRACTION = 0.45;
 const petKittyDropPx = (cellHeightPx: number): number =>
 	Math.min(Math.max(0, cellHeightPx - 1), Math.floor(cellHeightPx * KITTY_DROP_FRACTION));
 const PET_RAISE_ROWS = 1;
+const allocatedPetKittyImageIds = new Set<number>();
+
+function allocatePetKittyImageId(): number {
+	let id = 0;
+	while (id === 0 || allocatedPetKittyImageIds.has(id)) {
+		id = crypto.getRandomValues(new Uint32Array(1))[0] ?? 0;
+	}
+	allocatedPetKittyImageIds.add(id);
+	return id;
+}
+
+interface SixelFootprint {
+	x: number;
+	y: number;
+	columns: number;
+	rows: number;
+}
+
+function sameFootprint(left: SixelFootprint, right: SixelFootprint): boolean {
+	return left.x === right.x && left.y === right.y && left.columns === right.columns && left.rows === right.rows;
+}
+
+/**
+ * Which widget currently owns each TUI's single shared post-render emitter
+ * slot. A stale or repeated dispose (or off-switch) of a predecessor widget
+ * must never clear a successor's overlay authority.
+ */
+const petOverlayEmitterOwners = new WeakMap<TUI, GajaePetWidget>();
+
 /** Working animation: the shared para-para beats looped end to end. */
 const WORK_LOOP_TOTAL = PARA_PARA_STEPS.reduce((sum, [, ms]) => sum + ms, 0);
 /** Random gap between automatic claw flexes (fires while idle AND working). */
@@ -127,6 +155,20 @@ export class GajaePetWidget {
 	/** Cell metrics the current frames were built for; a change triggers a rebuild. */
 	#builtCellW = 0;
 	#builtCellH = 0;
+	#kittyImageId: number | undefined;
+	/** True while a kitty placement may exist on screen; cleared only after the delete escape is delivered. */
+	#kittyCleanupPending = false;
+	/** Last emitted Sixel raster position; retained until an erase is actually delivered. */
+	#lastSixelFootprint: SixelFootprint | undefined;
+	/** Terminal state: a disposed widget never touches the TUI or shared slots again. */
+	#disposed = false;
+	/**
+	 * True while the previous overlay frame carried the cleanup payload. The
+	 * TUI writes the frame after the emitter returns, so delivery is
+	 * acknowledged only on the next emitter pass — and only while the terminal
+	 * stayed available, since a failed render write drops availability.
+	 */
+	#frameCleanupAwaitingAck = false;
 
 	constructor(options: {
 		ui: TUI;
@@ -154,9 +196,7 @@ export class GajaePetWidget {
 
 	/** Protocol available for the real-pixel pet, if any. */
 	static pixelProtocol(): "sixel" | "kitty" | null {
-		if (TERMINAL.imageProtocol === ImageProtocol.Kitty) return "kitty";
-		if (TERMINAL.imageProtocol === ImageProtocol.Sixel) return "sixel";
-		return null;
+		return getPetPixelProtocol();
 	}
 
 	get mode(): PetMode {
@@ -182,14 +222,19 @@ export class GajaePetWidget {
 		}
 	}
 
+	commitPreviewMode(mode: PetMode): void {
+		this.#applyMode(mode, false);
+	}
+
 	#applyMode(mode: PetMode, mountComposer: boolean): void {
-		if (mode === this.#mode) return;
+		if (this.#disposed || mode === this.#mode) return;
 
 		if (mode === "off") {
+			this.#writeImageCleanup();
 			this.#mode = "off";
 			this.#animation?.unregister();
 			this.#animation = undefined;
-			this.#ui.setPostRenderEmitter(undefined);
+			this.#releaseOverlayEmitter();
 			this.#floorContainer.clear();
 			this.#pixel = undefined;
 			this.#framedEditor.setReserve(0);
@@ -200,6 +245,7 @@ export class GajaePetWidget {
 
 		const protocol = this.#forcedProtocol ?? GajaePetWidget.pixelProtocol();
 		if (!protocol) return;
+		if (this.#mode !== "off") this.#writeImageCleanup();
 		this.#mode = mode;
 		this.#frame = "base";
 		this.#flexUntil = 0;
@@ -210,6 +256,7 @@ export class GajaePetWidget {
 		// the composer stays pinned to the terminal bottom.
 		this.#floorContainer.clear();
 		this.#ui.setPostRenderEmitter(() => this.#overlayPayload());
+		petOverlayEmitterOwners.set(this.#ui, this);
 		this.#animation ??= registerAnimationCallback(now => this.#tick(now), 80);
 		this.#ui.requestRender(true);
 	}
@@ -220,6 +267,10 @@ export class GajaePetWidget {
 		this.#builtCellW = cell.widthPx;
 		this.#builtCellH = cell.heightPx;
 		const skin: PetSkinId = this.#mode === "off" ? "red" : this.#mode;
+		if (protocol === "kitty") {
+			this.#kittyImageId ??= allocatePetKittyImageId();
+			this.#kittyCleanupPending = true;
+		}
 		this.#pixel = buildGajaePixelFrames({
 			protocol,
 			skin,
@@ -228,17 +279,49 @@ export class GajaePetWidget {
 			targetRows: 2,
 			sixelTopPaddingPx: protocol === "sixel" ? PET_SIXEL_DROP_PX : 0,
 			kittyCellYOffsetPx: protocol === "kitty" ? petKittyDropPx(cell.heightPx) : 0,
+			kittyImageId: protocol === "kitty" ? this.#kittyImageId : undefined,
 		});
 		this.#framedEditor.setReserve(this.#pixel.columns + PET_SIDE_MARGIN);
 	}
 
 	dispose(): void {
-		this.#animation?.unregister();
-		this.#animation = undefined;
-		this.#ui.setPostRenderEmitter(undefined);
-		this.#floorContainer.clear();
-		this.#framedEditor.setReserve(0);
-		this.#mountEditor(false);
+		if (this.#disposed) return;
+		this.#disposed = true;
+		const kittyImageId = this.#kittyImageId;
+		const cleanupPayload = this.#imageCleanupPayload();
+		try {
+			if (cleanupPayload) {
+				this.#ui.queueTerminalCleanup(
+					`\x1b[?2026h\x1b7${cleanupPayload}\x1b8\x1b[?2026l`,
+					kittyImageId === undefined ? undefined : () => allocatedPetKittyImageIds.delete(kittyImageId),
+				);
+			} else if (kittyImageId !== undefined) {
+				allocatedPetKittyImageIds.delete(kittyImageId);
+			}
+			this.#consumeCleanupAuthority();
+			this.#kittyImageId = undefined;
+		} finally {
+			this.#animation?.unregister();
+			this.#animation = undefined;
+			this.#releaseOverlayEmitter();
+			this.#mode = "off";
+			this.#pixel = undefined;
+			this.#floorContainer.clear();
+			this.#framedEditor.setReserve(0);
+			// Restore the plain composer only while our framed wrapper is still
+			// mounted; a successor widget may already own the editor container.
+			if (this.#editorContainer.children.includes(this.#framedEditor)) {
+				this.#mountEditor(false);
+			}
+		}
+	}
+
+	/** Clear the shared post-render slot only while this widget still owns it. */
+	#releaseOverlayEmitter(): void {
+		if (petOverlayEmitterOwners.get(this.#ui) === this) {
+			this.#ui.setPostRenderEmitter(undefined);
+			petOverlayEmitterOwners.delete(this.#ui);
+		}
 	}
 
 	#mountEditor(framed: boolean): void {
@@ -335,25 +418,91 @@ export class GajaePetWidget {
 		return { x, y };
 	}
 
-	#clearPetPayload(x: number, y: number): string {
-		const pixel = this.#pixel;
-		if (pixel?.protocol !== "sixel") return "";
+	#clearSixelFootprint(footprint: SixelFootprint): string {
 		let out = "\x1b[0m";
-		for (let row = 0; row < pixel.rasterRows; row++) {
-			out += `\x1b[${y + row + 1};${x + 1}H\x1b[${pixel.columns}X`;
+		for (let row = 0; row < footprint.rows; row++) {
+			out += `\x1b[${footprint.y + row + 1};${footprint.x + 1}H\x1b[${footprint.columns}X`;
+		}
+		return out;
+	}
+
+	/** Pending on-screen image cleanup. Pure: authority is consumed separately, on delivery. */
+	#imageCleanupPayload(): string {
+		let out = "";
+		if (this.#kittyCleanupPending && this.#kittyImageId !== undefined) {
+			out += `\x1b_Ga=d,d=I,i=${this.#kittyImageId},q=2\x1b\\`;
+		}
+		if (this.#lastSixelFootprint) {
+			out += this.#clearSixelFootprint(this.#lastSixelFootprint);
 		}
 		return out;
 	}
 
+	#consumeCleanupAuthority(): void {
+		this.#kittyCleanupPending = false;
+		this.#lastSixelFootprint = undefined;
+	}
+
+	/**
+	 * Best-effort direct erase of the on-screen pet image. Cleanup authority is
+	 * consumed only after the write is actually delivered: an unavailable
+	 * terminal or a throwing write keeps the erase pending so a later mode
+	 * switch or dispose can retry it.
+	 */
+	#writeImageCleanup(): void {
+		if (!this.#ui.terminalAvailable) return;
+		const payload = this.#imageCleanupPayload();
+		if (!payload) return;
+		try {
+			this.#ui.terminal.write(`\x1b[?2026h\x1b7${payload}\x1b8\x1b[?2026l`);
+		} catch {
+			// Keep the footprint/placement authority; the terminal write layer
+			// reports availability separately and callers retry on the next
+			// lifecycle transition.
+			return;
+		}
+		this.#consumeCleanupAuthority();
+	}
+
 	/** Draw escape payload at the pet's absolute position. */
 	#overlayPayload(clearPet = false): string | null {
 		const pixel = this.#pixel;
 		if (!pixel) return null;
 		const pos = this.#petPosition();
-		if (!pos) return null;
+		if (!pos) {
+			// Deferred delivery acknowledgement: the TUI writes the frame after
+			// this emitter returns, and that write can fail. Consume the cleanup
+			// authority only once a later pass observes the terminal survived
+			// the frame that carried the payload; otherwise retain it so a later
+			// lifecycle cleanup retries the erase/delete.
+			if (this.#frameCleanupAwaitingAck && this.#ui.terminalAvailable) {
+				this.#consumeCleanupAuthority();
+			}
+			this.#frameCleanupAwaitingAck = false;
+			if (!this.#ui.terminalAvailable) return null;
+			const cleanup = this.#imageCleanupPayload();
+			if (!cleanup) return null;
+			this.#frameCleanupAwaitingAck = true;
+			return cleanup;
+		}
+		// A full frame supersedes any cleanup-only frame still awaiting ack.
+		this.#frameCleanupAwaitingAck = false;
 		const { x, y } = pos;
+		let out = "";
+
+		if (pixel.protocol === "sixel") {
+			const footprint = { x, y, columns: pixel.columns, rows: pixel.rasterRows };
+			if (this.#lastSixelFootprint && !sameFootprint(this.#lastSixelFootprint, footprint)) {
+				out += this.#clearSixelFootprint(this.#lastSixelFootprint);
+			}
+			if (clearPet) out += this.#clearSixelFootprint(footprint);
+			this.#lastSixelFootprint = footprint;
+		} else {
+			// A kitty frame emitted below (re)places the image, so cleanup is
+			// pending again even if a narrow-terminal pass consumed it earlier.
+			this.#kittyCleanupPending = true;
+		}
 
-		let out = clearPet ? this.#clearPetPayload(x, y) : "";
 		out += `\x1b[${y + 1};${x + 1}H${pixel.frames[this.#frame]}`;
 		return out;
 	}

package/src/modes/components/pet-capability.ts

@@ -0,0 +1,115 @@
+import {
+	ImageProtocol,
+	isUnderTerminalMultiplexer,
+	onImageProtocolChanged,
+	type SelectItem,
+	shouldProbeSixelCapability,
+	TERMINAL,
+} from "@gajae-code/tui";
+
+export type PetPixelProtocol = "sixel" | "kitty";
+
+export const PET_UNAVAILABLE_DESCRIPTION = "Unavailable: requires compatible Kitty or Sixel overlay rendering";
+export const PET_SAVED_UNAVAILABLE_DESCRIPTION =
+	"Saved, unavailable — requires compatible Kitty or Sixel overlay rendering";
+export const PET_UNAVAILABLE_WARNING =
+	"⚠ Pets aren’t available in this terminal. Its image support isn’t compatible with Gajae Pet’s overlay rendering yet. Try Kitty, Ghostty, WezTerm, or a terminal with compatible Sixel support.";
+const PET_MULTIPLEXER_UNAVAILABLE_WARNING =
+	"⚠ Gajae Pet graphics are unavailable inside tmux, screen, or zellij because image escapes are not forwarded end to end. Run gjc outside the multiplexer, or set PI_FORCE_IMAGE_PROTOCOL=sixel only when the full terminal chain supports Sixel.";
+
+export function getPetUnavailableWarning(env: NodeJS.ProcessEnv = Bun.env): string {
+	return isUnderTerminalMultiplexer(env) ? PET_MULTIPLEXER_UNAVAILABLE_WARNING : PET_UNAVAILABLE_WARNING;
+}
+
+export function getPetPixelProtocol(): PetPixelProtocol | null {
+	if (TERMINAL.imageProtocol === ImageProtocol.Kitty) return "kitty";
+	if (TERMINAL.imageProtocol === ImageProtocol.Sixel) return "sixel";
+	return null;
+}
+
+export function isPetAvailable(): boolean {
+	return getPetPixelProtocol() !== null;
+}
+
+export function createPetSelectItems(
+	options: ReadonlyArray<SelectItem>,
+	currentValue: string,
+	available: boolean,
+): SelectItem[] {
+	return options.map(option => {
+		const disabled = !available && option.value !== "off";
+		const current = option.value === currentValue;
+		const savedUnavailable = disabled && current;
+		let description = `${option.description ?? ""}${current ? " (current)" : ""}`;
+		if (disabled) {
+			description = savedUnavailable ? PET_SAVED_UNAVAILABLE_DESCRIPTION : PET_UNAVAILABLE_DESCRIPTION;
+		}
+		return {
+			...option,
+			label: savedUnavailable ? `${option.label} (saved)` : option.label,
+			description,
+			disabled,
+		};
+	});
+}
+
+/**
+ * Grace period before declaring the terminal pet-incapable at startup. The
+ * asynchronous Sixel capability probe starts inside `TUI.start()` and answers
+ * within its own 250 ms deadline; this margin covers probe scheduling so a
+ * supported terminal is never told it is incompatible while the probe is
+ * still in flight.
+ */
+export const PET_CAPABILITY_SETTLE_MS = 1_000;
+
+/**
+ * Whether the asynchronous startup Sixel capability probe may still enable
+ * graphics for this session, meaning current unavailability is not final.
+ */
+export function isPetCapabilityProbePending(
+	env: NodeJS.ProcessEnv = Bun.env,
+	platform: NodeJS.Platform = process.platform,
+): boolean {
+	if (TERMINAL.imageProtocol !== null) return false;
+	if (!process.stdin.isTTY || !process.stdout.isTTY) return false;
+	return shouldProbeSixelCapability(env, platform);
+}
+
+/**
+ * Deliver the pet-unavailable startup warning only once the capability
+ * question is settled. With no probe pending, unavailability is final and
+ * `onUnavailable` fires immediately. While a probe may still enable
+ * graphics, the warning is deferred: a protocol-change event cancels it (the
+ * saved pet re-applies through the existing subscription), and only the
+ * settle deadline passing with the terminal still unavailable emits it.
+ * Returns a disposer that cancels the pending decision.
+ */
+export function warnWhenPetCapabilitySettled(options: {
+	probePending: boolean;
+	isAvailable?: () => boolean;
+	onUnavailable: () => void;
+	settleMs?: number;
+}): () => void {
+	if (!options.probePending) {
+		options.onUnavailable();
+		return () => {};
+	}
+	const isAvailable = options.isAvailable ?? isPetAvailable;
+	let settled = false;
+	const finish = () => {
+		if (settled) return;
+		settled = true;
+		clearTimeout(timer);
+		unsubscribe();
+	};
+	const unsubscribe = onImageProtocolChanged(protocol => {
+		if (!protocol) return;
+		finish();
+	});
+	const timer = setTimeout(() => {
+		finish();
+		if (!isAvailable()) options.onUnavailable();
+	}, options.settleMs ?? PET_CAPABILITY_SETTLE_MS);
+	timer.unref?.();
+	return finish;
+}

package/src/modes/components/pet-selector.ts

@@ -1,7 +1,8 @@
-import { Container, PET_SKIN_IDS, PET_SKINS, type SelectItem, SelectList } from "@gajae-code/tui";
+import { Container, PET_SKIN_IDS, PET_SKINS, SelectList } from "@gajae-code/tui";
 import { getSelectListTheme } from "../theme/theme";
 import { DynamicBorder } from "./dynamic-border";
 import type { PetMode } from "./gajae-pet-widget";
+import { createPetSelectItems } from "./pet-capability";
 
 const PET_OPTIONS: { value: PetMode; label: string; description: string }[] = [
 	{ value: "off", label: "Off", description: "No pet" },
@@ -24,14 +25,11 @@ export class PetSelectorComponent extends Container {
 		onSelect: (mode: PetMode) => void,
 		onCancel: () => void,
 		onPreview: (mode: PetMode) => void,
+		available: boolean,
 	) {
 		super();
 
-		const items: SelectItem[] = PET_OPTIONS.map(option => ({
-			value: option.value,
-			label: option.label,
-			description: option.value === current ? `${option.description} (current)` : option.description,
-		}));
+		const items = createPetSelectItems(PET_OPTIONS, current, available);
 
 		this.addChild(new DynamicBorder());
 

package/src/modes/components/settings-selector.ts

@@ -25,6 +25,7 @@ import { getCurrentThemeName, getSelectListTheme, getSettingsListTheme, theme }
 import { matchesAppInterrupt } from "../../modes/utils/keybinding-matchers";
 import { getTabBarTheme } from "../shared";
 import { DynamicBorder } from "./dynamic-border";
+import { createPetSelectItems, getPetUnavailableWarning, isPetAvailable } from "./pet-capability";
 import { handleInputOrEscape, PluginSettingsComponent } from "./plugin-settings";
 import { getSettingsForTab, type SettingDef } from "./settings-defs";
 import type { StatusLineSegmentOptions } from "./status-line";
@@ -661,6 +662,8 @@ export interface SettingsRuntimeContext {
 	availableModelProfiles: string[];
 	/** Working directory for plugins tab */
 	cwd: string;
+	/** Whether this terminal can render the pet overlay. */
+	petAvailable?: boolean;
 }
 
 /** Status line settings subset for preview */
@@ -684,6 +687,13 @@ export interface SettingsCallbacks {
 	onThemePreviewCancel?: (theme: string) => void | Promise<void>;
 	/** Called to live-preview the gajae pet skin while browsing the pet setting. */
 	onPetPreview?: (mode: string) => void;
+	/**
+	 * Commit a pet mode through the shared result-returning policy. The policy
+	 * rechecks capability immediately before mutation and owns persistence, so
+	 * the settings surface never persists `pet.mode` ahead of acceptance.
+	 * Returns whether the commit was accepted.
+	 */
+	onPetCommit?: (mode: string) => boolean;
 	/** Called for status line preview while configuring */
 	onStatusLinePreview?: (settings: StatusLinePreviewSettings) => void;
 	/** Get current rendered status line for inline preview */
@@ -841,7 +851,7 @@ export class SettingsSelectorComponent extends Container {
 		currentValue: string,
 		done: (value?: string) => void,
 	): Container {
-		let options = def.options;
+		let options: ReadonlyArray<SelectItem> = def.options;
 
 		// Special case: inject runtime options for thinking level
 		if (def.path === "defaultThinkingLevel") {
@@ -857,6 +867,14 @@ export class SettingsSelectorComponent extends Container {
 		if (def.path === "statusLine.preset") {
 			options = options.filter(option => option.value !== "custom");
 		}
+		let description = def.description;
+		if (def.path === "pet.mode") {
+			const petAvailable = this.context.petAvailable ?? isPetAvailable();
+			options = createPetSelectItems(options, currentValue, petAvailable);
+			// Unsupported terminals must see the same actionable guidance the
+			// startup notice and /pet show, not only dimmed option descriptions.
+			if (!petAvailable) description = getPetUnavailableWarning();
+		}
 		// Preview handlers
 		let onPreview: ((value: string) => void | Promise<void>) | undefined;
 		let onPreviewCancel: (() => void) | undefined;
@@ -943,10 +961,18 @@ export class SettingsSelectorComponent extends Container {
 
 		return new SelectSubmenu(
 			def.label,
-			def.description,
+			description,
 			options,
 			currentValue,
 			value => {
+				if (def.path === "pet.mode") {
+					// The shared pet commit policy rechecks capability immediately
+					// before mutation and persists only on acceptance; the settings
+					// surface must not persist ahead of that result.
+					const accepted = this.callbacks.onPetCommit?.(value) ?? false;
+					done(accepted ? value : undefined);
+					return;
+				}
 				this.#setSettingValue(def.path, value);
 				this.callbacks.onChange(def.path, value);
 				done(value);

package/src/modes/controllers/extension-ui-controller.ts

@@ -50,6 +50,11 @@ export class ExtensionUiController {
 		overlay?.hide();
 	}
 
+	/** Re-mount the pet-aware composer after a transient hook UI closes. */
+	#restoreComposerEditor(): void {
+		this.ctx.restoreComposer();
+	}
+
 	/**
 	 * Initialize the hook system with TUI-based UI context.
 	 */
@@ -723,8 +728,7 @@ export class ExtensionUiController {
 	 */
 	hideHookSelector(): void {
 		this.ctx.hookSelector?.dispose();
-		this.ctx.editorContainer.clear();
-		this.ctx.editorContainer.addChild(this.ctx.editor);
+		this.#restoreComposerEditor();
 		this.ctx.hookSelector = undefined;
 		this.ctx.ui.setFocus(this.ctx.editor);
 		this.ctx.ui.requestRender();
@@ -785,8 +789,7 @@ export class ExtensionUiController {
 	 */
 	hideHookInput(): void {
 		this.ctx.hookInput?.dispose();
-		this.ctx.editorContainer.clear();
-		this.ctx.editorContainer.addChild(this.ctx.editor);
+		this.#restoreComposerEditor();
 		this.ctx.hookInput = undefined;
 		this.ctx.ui.setFocus(this.ctx.editor);
 		this.ctx.ui.requestRender();
@@ -835,8 +838,7 @@ export class ExtensionUiController {
 	 * Hide the hook editor.
 	 */
 	hideHookEditor(): void {
-		this.ctx.editorContainer.clear();
-		this.ctx.editorContainer.addChild(this.ctx.editor);
+		this.#restoreComposerEditor();
 		this.ctx.hookEditor = undefined;
 		this.ctx.ui.setFocus(this.ctx.editor);
 		this.ctx.ui.requestRender();
@@ -879,8 +881,7 @@ export class ExtensionUiController {
 			closed = true;
 			this.#clearActiveHookCustom();
 			if (!options?.overlay) {
-				this.ctx.editorContainer.clear();
-				this.ctx.editorContainer.addChild(this.ctx.editor);
+				this.#restoreComposerEditor();
 				this.ctx.editor.setText(savedText);
 			}
 			this.ctx.ui.setFocus(this.ctx.editor);

package/src/modes/controllers/input-controller.ts

@@ -434,13 +434,14 @@ export class InputController {
 			}
 
 			const runner = this.ctx.session.extensionRunner;
+			const pendingImages = this.ctx.pendingImages;
 			let inputImages = this.#visiblePendingImagesForText(text);
 
 			if (runner?.hasHandlers("input")) {
 				const result = await runner.emitInput(text, inputImages, "interactive");
 				if (result?.handled) {
 					this.ctx.editor.setText("");
-					this.ctx.pendingImages = [];
+					this.#clearPendingImagesIfOwnedBy(pendingImages);
 					return;
 				}
 				if (result?.text !== undefined) {
@@ -530,7 +531,7 @@ export class InputController {
 				this.ctx.editor.addToHistory(text);
 				this.ctx.editor.setText("");
 				const images = inputImages && inputImages.length > 0 ? [...inputImages] : undefined;
-				this.ctx.pendingImages = [];
+				this.#clearPendingImagesIfOwnedBy(pendingImages);
 				// Record the signature so the queued message's eventual delivery
 				// (a user-role `message_start` event) leaves any draft the user has
 				// typed since queuing intact. Same protection as #783, applied to
@@ -582,7 +583,7 @@ export class InputController {
 			if (this.ctx.onInputCallback) {
 				// Include any pending images from clipboard paste
 				const images = inputImages && inputImages.length > 0 ? [...inputImages] : undefined;
-				this.ctx.pendingImages = [];
+				this.#clearPendingImagesIfOwnedBy(pendingImages);
 
 				// Render user message immediately, then let session events catch up
 				const submission = this.ctx.startPendingSubmission({ text, images });
@@ -1104,11 +1105,14 @@ export class InputController {
 				return false;
 			}
 
-			this.ctx.pendingImages.push({
-				type: "image",
-				data: image.data,
-				mimeType: image.mimeType,
-			});
+			this.ctx.pendingImages = [
+				...this.ctx.pendingImages,
+				{
+					type: "image",
+					data: image.data,
+					mimeType: image.mimeType,
+				},
+			];
 			this.ctx.editor.insertText(`${formatPastedImageReference(this.#nextImagePlaceholder(), image.resolvedPath)} `);
 			this.ctx.showStatus(`Attached image: ${path.basename(image.resolvedPath)}`, { dim: true });
 			this.ctx.ui.requestRender();
@@ -1151,10 +1155,33 @@ export class InputController {
 		return images.length > 0 ? images : undefined;
 	}
 
+	#clearPendingImagesIfOwnedBy(pendingImages: InteractiveModeContext["pendingImages"]): void {
+		if (this.ctx.pendingImages === pendingImages) {
+			this.ctx.pendingImages = [];
+		}
+	}
+
 	#clearPendingImagesIfPlaceholdersRemoved(text: string): void {
 		if (this.ctx.pendingImages.length === 0 || IMAGE_PLACEHOLDER_PRESENT_PATTERN.test(text)) {
 			return;
 		}
+		// Editor submit resets the composer and emits onChange("") before onSubmit(result).
+		// Defer the empty-buffer clear so the submit handler can still resolve image
+		// placeholders against pendingImages, while manual clears still drop stale images.
+		if (text.length === 0) {
+			const pendingImages = this.ctx.pendingImages;
+			const pendingImageCount = pendingImages.length;
+			queueMicrotask(() => {
+				if (
+					this.ctx.pendingImages === pendingImages &&
+					pendingImages.length === pendingImageCount &&
+					this.ctx.editor.getText().length === 0
+				) {
+					this.ctx.pendingImages = [];
+				}
+			});
+			return;
+		}
 		this.ctx.pendingImages = [];
 	}
 
@@ -1185,11 +1212,14 @@ export class InputController {
 					}
 				}
 
-				this.ctx.pendingImages.push({
-					type: "image",
-					data: imageData.data,
-					mimeType: imageData.mimeType,
-				});
+				this.ctx.pendingImages = [
+					...this.ctx.pendingImages,
+					{
+						type: "image",
+						data: imageData.data,
+						mimeType: imageData.mimeType,
+					},
+				];
 				this.ctx.editor.insertText(`${this.#nextImagePlaceholder()} `);
 				this.ctx.ui.requestRender();
 				return true;