gentle-pi 4.2.0 → 4.4.0

package/extensions/gentle-shell.ts

@@ -1,7 +1,10 @@
 import { CustomEditor, keyHint, type ExtensionAPI, type ExtensionContext, type KeybindingsManager } from "@earendil-works/pi-coding-agent";
 import { isHomeOrBroadUserDirectory } from "../lib/bounded-writer-admission.ts";
-import { Editor, decodeKittyPrintable, isKeyRelease, matchesKey, parseKey, truncateToWidth, visibleWidth, type EditorTheme, type TUI } from "@earendil-works/pi-tui";
+import { Editor, Image, decodeKittyPrintable, getCapabilities, isKeyRelease, matchesKey, parseKey, truncateToWidth, visibleWidth, type EditorTheme, type TUI } from "@earendil-works/pi-tui";
+import { readClipboardImage, type ClipboardImage } from "../lib/clipboard-image.ts";
+import { describeAttachment, ImageAttachments } from "../lib/image-attachments.ts";
 import { execFile, spawnSync } from "node:child_process";
+import { openInExternalEditor, type ExternalEditorHost } from "../lib/external-editor.ts";
 import { existsSync, realpathSync, statSync } from "node:fs";
 import { lstat, readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
@@ -10,8 +13,9 @@ import { resolveSessionProfile, sessionProfileLabel, sessionProfileModelProfiles
 import * as os from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { buildShellHeaderModel, renderShellBar, renderShellBelowInputFloat, renderShellBottomOnlyBar, renderShellHeaderChrome, renderShellSidebarBar, keepNativeWorkingRow, shellEnabled, shellHeaderUsageHit, shellJobsCount, type ShellBarModel, type ShellBarTheme } from "../lib/shell-bar.ts";
-import { CHANGE_STATUS, DIFF_MAX_BYTES, DIFF_MAX_LINES, DIFF_TOO_LARGE, WorktreeChangesTracker, renderChangesWidget, type ChangedFile, type ChangesModel, type FileRevision, type GitRunner, type LineCounter, type WorktreeChanges } from "../lib/shell-changes.ts";
+import { CHANGE_STATUS, DIFF_MAX_BYTES, DIFF_MAX_LINES, DIFF_TOO_LARGE, WorktreeChangesTracker, changesDigest, renderChangesWidget, type ChangedFile, type ChangesModel, type FileRevision, type GitRunner, type LineCounter, type WorktreeChanges } from "../lib/shell-changes.ts";
 import { WorktreeChangesView } from "../lib/shell-changes-view.ts";
+import { createNativeFullscreenInteraction } from "../lib/native-fullscreen-interaction.ts";
 import { SessionWorktreeRegistry, resolveSessionWorktree, worktreeGitEnvironment, type WorktreeResolver, type WorktreeIdentity } from "../lib/session-worktree-registry.ts";
 import { CARD_STYLE, CARD_TONE, cardStyle, renderCard, setCardStyle, type Card, type CardTheme } from "../lib/shell-card.ts";
 import { resolveCardStyle, writeCardStyle } from "../lib/card-style-policy.ts";
@@ -21,17 +25,18 @@ import { buildCommandPaletteGroups } from "../lib/command-palette-catalog.ts";
 import { discoverYoloUiAdapter, YOLO_DISPLAY, type YoloDisplay, type YoloUiAdapter } from "../lib/yolo-session-policy.ts";
 import { VisualCustomizeView, type CustomizeCategory, type CustomizeRow, type ProfileActions } from "../lib/visual-customize-view.ts";
 import { deleteVisualProfile, getVisualProfile, listVisualProfiles, resetVisualProfiles, saveVisualProfile } from "../lib/visual-profiles.ts";
+import { gaugePaintFor } from "../lib/gauge-theme.ts";
+import type { GaugePaint } from "../lib/shell-gauge.ts";
 import { sourcePalettePreview } from "../lib/theme-customization.ts";
 import { DEFAULT_VISUAL_SETTINGS, DENSITY, HEADER_PLACEMENT, STATUS_PLACEMENT, VISUAL_SECTION_KEYS, resolveVisualSettings, writeVisualSettings } from "../lib/visual-customization-policy.ts";
 import { BANNER_COLORS, DEFAULT_BANNER_CONFIG, readBannerConfig, readBannerConfigForEdit, writeBannerConfig } from "./startup-banner.ts";
 import { agentsViewKey } from "../lib/agents-keys.ts";
 import { GentleAiDevBinaryOverrideError, resolveGentleAiDevBinaryOverride } from "../lib/gentle-ai-binary.ts";
-import { DOUBLE_ESC_CANCEL_HINT, floatPromptRow, framePromptLines, resolvePromptLayout, IDLE_ESC_CLEAR_HINT, PROMPT_HINT, PROMPT_STATE, SHELL_PULSE_MS, withPromptHint, type PromptState } from "../lib/shell-prompt.ts";
+import { DOUBLE_ESC_CANCEL_HINT, floatPromptRow, framePromptLines, resolvePromptLayout, IDLE_ESC_CLEAR_HINT, PROMPT_HINT, PROMPT_STATE, SHELL_PULSE_WATCHDOG_MS, withPromptHint, type PromptState } from "../lib/shell-prompt.ts";
 import { oddPhaseRegistry } from "../lib/odd-phase.ts";
 import { inferOddPhase } from "../lib/odd-phase-inference.ts";
 import { isInteractiveMode } from "../lib/rpc-host.ts";
 import { gentlePiConfigHome } from "../lib/agent-home.ts";
-import { bundledGentlePiConfigHome } from "../lib/gentle-shell-bundled.ts";
 import { isNanAdaptiveReasoningModel } from "../lib/nan-provider.ts";
 import { resolveAnimationPolicy, writeAnimationPolicy, type AnimationPolicy } from "../lib/animation-policy.ts";
 import { resolveVimPolicy, writeVimPolicy, type VimPolicy } from "../lib/vim-policy.ts";
@@ -169,6 +174,8 @@ export interface ShellDeps {
 	/** A root Changes may scan: removed worktrees and leftover directories are skipped. */
 	rootExists(root: string): boolean;
 	vimRuntimeVersion?(): string | undefined;
+	/** Clipboard image source for the prompt's attachment chips; tests inject a fake. */
+	readClipboardImage?(): Promise<ClipboardImage | null>;
 }
 
 export type ActiveProfileReader = (() => string | undefined) & {
@@ -180,7 +187,7 @@ export type ActiveProfileReader = (() => string | undefined) & {
 // Unbound reads retain the global file-identity cache, including atomic replacements.
 // Bound reads are snapshots: no filesystem or Git work is done during a frame.
 export function createActiveProfileReader(env: NodeJS.ProcessEnv = process.env): ActiveProfileReader {
-	const path = profilesFilePath(bundledGentlePiConfigHome(env) ?? env.GENTLE_PI_CONFIG_HOME ?? join(os.homedir(), ".pi", "gentle-ai"));
+	const path = profilesFilePath(gentlePiConfigHome(env));
 	let fingerprint: string | undefined;
 	let name: string | undefined;
 	let bound = false;
@@ -215,7 +222,7 @@ export function createActiveProfileReader(env: NodeJS.ProcessEnv = process.env):
 		const next = cwd === undefined ? global() : sessionProfileLabel(resolveSessionProfile({
 			sessionId,
 			cwd,
-			configHome: bundledGentlePiConfigHome(env) ?? env.GENTLE_PI_CONFIG_HOME ?? join(os.homedir(), ".pi", "gentle-ai"),
+			configHome: gentlePiConfigHome(env),
 			resolveWorktree: () => identity,
 			env,
 		}));
@@ -272,33 +279,38 @@ function sessionCost(ctx: ExtensionContext): number {
 }
 
 type ShellSessionStats = { costTotal: number; usage: ReturnType<ExtensionContext["getContextUsage"]> };
-const shellSessionStats = new WeakMap<object, {
-	sessionId: string | undefined;
-	leafId: string | null;
-	entryCount: number | undefined;
-	model: ExtensionContext["model"];
-	contextWindow: number | undefined;
-	stats: ShellSessionStats;
-}>();
-
-function sessionStats(ctx: ExtensionContext): ShellSessionStats {
+// The exact identity sessionStats' memo keys on: when any element differs the
+// stats are recomputed. Undefined means the host lacks the leaf identity and
+// the stats must be computed fresh on every call. Callers that digest live
+// state per frame (issue #1681) reuse this key so their own memos can never
+// disagree with sessionStats about what is still current.
+type SessionStatsKey = readonly [
+	sessionId: string | undefined,
+	leafId: string | null,
+	entryCount: number | undefined,
+	model: ExtensionContext["model"],
+	contextWindow: number | undefined,
+];
+const shellSessionStats = new WeakMap<object, { key: SessionStatsKey; stats: ShellSessionStats }>();
+
+function sessionStatsKey(ctx: ExtensionContext): SessionStatsKey | undefined {
 	const manager = ctx.sessionManager as ExtensionContext["sessionManager"] & { getEntryCount?(): number };
-	const compute = (): ShellSessionStats => ({ costTotal: sessionCost(ctx), usage: ctx.getContextUsage() });
 	// Append-only session entries move the leaf, including compaction and branch
 	// switches. A virtual model's routed physical model comes from the latest
 	// response, which is appended as an entry, so the leaf covers it as well.
 	// Older/test hosts without that identity must stay uncached.
-	if (typeof manager.getLeafId !== "function") return compute();
-	const sessionId = manager.getSessionId();
-	const leafId = manager.getLeafId();
-	const entryCount = manager.getEntryCount?.();
-	const model = ctx.model;
-	const contextWindow = model?.contextWindow;
-	const cached = shellSessionStats.get(manager);
-	if (cached && cached.sessionId === sessionId && cached.leafId === leafId &&
-		cached.entryCount === entryCount && cached.model === model && cached.contextWindow === contextWindow) return cached.stats;
+	if (typeof manager.getLeafId !== "function") return undefined;
+	return [manager.getSessionId(), manager.getLeafId(), manager.getEntryCount?.(), ctx.model, ctx.model?.contextWindow] as const;
+}
+
+function sessionStats(ctx: ExtensionContext): ShellSessionStats {
+	const compute = (): ShellSessionStats => ({ costTotal: sessionCost(ctx), usage: ctx.getContextUsage() });
+	const key = sessionStatsKey(ctx);
+	if (!key) return compute();
+	const cached = shellSessionStats.get(ctx.sessionManager);
+	if (cached && cached.key.every((value, index) => value === key[index])) return cached.stats;
 	const stats = compute();
-	shellSessionStats.set(manager, { sessionId, leafId, entryCount, model, contextWindow, stats });
+	shellSessionStats.set(ctx.sessionManager, { key, stats });
 	return stats;
 }
 
@@ -334,6 +346,85 @@ export function buildShellBarModel(
 	};
 }
 
+export interface FooterStatusMemoDeps {
+	pi: ExtensionAPI;
+	ctx: ExtensionContext;
+	footerData: ShellFooterData;
+	usage: () => ProviderUsage | undefined;
+	profile: () => string | undefined;
+	jobs: () => RunningJobDisplay[] | undefined;
+	review: () => ReviewSidebarSnapshot | undefined;
+	tracker: () => Pick<WorktreeChangesTracker, "model" | "unbornRoots">;
+	visualSettings: () => unknown;
+	cardStyle: () => unknown;
+}
+
+// Issue #1681: railDigest evaluates every rail's digest before the fullscreen
+// layout's prepared cache can answer, so both Status rails digest per
+// keystroke and a cache hit still paid for building and serializing the whole
+// bar model. The memo keys on the cheap live inputs the model reads instead:
+// the digest serializes only this key, and the model is rebuilt just when one
+// of those inputs moved. On hosts without leaf identity the session stats
+// stay uncached and ride the key by value, so those hosts keep exactly the
+// pre-memo digest honesty.
+export function createFooterStatusMemo(deps: FooterStatusMemoDeps): { key(): string; model(): ShellBarModel } {
+	const { pi, ctx, footerData } = deps;
+	let cache: { key: string; model: ShellBarModel } | undefined;
+	const key = (): string => {
+		const statsKey = sessionStatsKey(ctx);
+		const model = ctx.model;
+		return JSON.stringify([
+			// Session statistics identity by value: without leaf identity the
+			// computed stats ride the key, so those hosts keep exactly the pre-memo
+			// digest honesty. The model rides its value pieces (id, contextWindow,
+			// effort lookup, OAuth state) because that is all buildShellBarModel
+			// reads — serializing the model object itself would bloat every digest.
+			statsKey ? [statsKey[0], statsKey[1], statsKey[2]] : sessionStats(ctx),
+			model?.id ?? null,
+			model?.contextWindow ?? null,
+			model?.reasoning ? (isNanAdaptiveReasoningModel(model) ? "auto" : pi.getThinkingLevel()) : undefined,
+			model ? ctx.modelRegistry.isUsingOAuth(model) : false,
+			footerData.getGitBranch(),
+			deps.profile(),
+			ctx.sessionManager.getSessionName(),
+			ctx.sessionManager.getCwd(),
+			[...footerData.getExtensionStatuses()].sort(([a], [b]) => a.localeCompare(b)),
+			deps.usage(),
+			deps.jobs(),
+			deps.review(),
+			(() => {
+				const { model: changes, unbornRoots } = deps.tracker();
+				return { fingerprint: changesFingerprint(changes), files: changes.files.length, added: changes.added, deleted: changes.deleted, unbornRoots: unbornRoots.length };
+			})(),
+			deps.visualSettings(),
+			deps.cardStyle(),
+		]);
+	};
+	const model = (): ShellBarModel => {
+		const k = key();
+		if (cache?.key === k) return cache.model;
+		const tracker = deps.tracker();
+		const built: ShellBarModel = {
+			...buildShellBarModel(pi, ctx, footerData, { dirty: tracker.model.files.length, usage: deps.usage(), profile: deps.profile(), jobs: deps.jobs() }),
+			changes: { files: tracker.model.files.length, added: tracker.model.added, deleted: tracker.model.deleted },
+			review: deps.review(),
+		};
+		cache = { key: k, model: built };
+		return built;
+	};
+	return { key, model };
+}
+
+// Gauge-specific theme roles (issue #2222): resolved from the installed theme
+// source and memoized by gauge-theme.ts, so the render hot path only stats the
+// theme file. Undefined — and therefore today's shared roles — whenever the theme
+// source is unavailable.
+function gaugePaint(ctx: ExtensionContext): GaugePaint | undefined {
+	const themeName = ctx.ui.theme.name;
+	const source = ctx.ui.theme.sourcePath ?? ctx.ui.getAllThemes?.().find((item) => item?.name === themeName)?.path;
+	return gaugePaintFor(typeof source === "string" ? source : undefined);
+}
+
 export function createShellBarComponent(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
@@ -350,7 +441,7 @@ export function createShellBarComponent(
 	});
 	return {
 		render(width: number) {
-			return renderShellBar(buildShellBarModel(pi, ctx, footerData, { dirty: dirty(), usage: usage() }), theme, width, presentation?.());
+			return renderShellBar(buildShellBarModel(pi, ctx, footerData, { dirty: dirty(), usage: usage() }), theme, width, presentation?.(), gaugePaint(ctx));
 		},
 		invalidate() {},
 		dispose() {
@@ -380,6 +471,11 @@ interface PromptEditorDeps {
 	 * generic "working…" label. Never applied to IDLE or QUEUED.
 	 */
 	workingLabel?: () => string | undefined;
+	/** Pasted images become atomic `[Image#N]` chips; absent, Pi's paste handler runs unchanged. */
+	attachments?: ImageAttachments;
+	readClipboardImage?: () => Promise<ClipboardImage | null>;
+	/** Injectable silence-watchdog window; production and tests default to SHELL_PULSE_WATCHDOG_MS. */
+	watchdogMs?: number;
 }
 
 const PROMPT_FRAME_ROLE = "border";
@@ -434,7 +530,10 @@ export class GentlePromptEditor extends CustomEditor {
 	private visualReplacePending = false;
 	private visualObjectPending: "i" | "a" | undefined;
 	private visualAnchor: { line: number; col: number } | undefined;
-	private pulse: NodeJS.Timeout | undefined;
+	private watchdog: NodeJS.Timeout | undefined;
+	// Last time a frame painted (or the watchdog forced one) while working; the
+	// quality watchdog repaints only when now() drifts past its window.
+	private lastRenderAt = 0;
 	private readonly deps: PromptEditorDeps;
 	private floatMouseLayout?: ReturnType<typeof resolvePromptLayout>;
 	// Native selection engine (shift+home/end, alt+a, replace-on-key): ported
@@ -452,19 +551,97 @@ export class GentlePromptEditor extends CustomEditor {
 	// the text is still exactly this, so an edit in between never gets
 	// silently discarded (issue #1218 review).
 	private pendingIdleClearText: string | undefined;
+	// Pi's own paste handler (files, text, unsupported formats). Pi assigns
+	// `onPasteImage` after construction; the accessor below keeps it as the
+	// fallback and routes every paste key, Vim NORMAL included, to pasteImage.
+	private piPasteImage: (() => void) | undefined;
+	private pastingImage = false;
+	private disposed = false;
+	// Counts submitted drafts, so a clipboard read that resolves after its
+	// draft was sent never lands in (and rides along with) the next message.
+	private submittedDrafts = 0;
 
 	constructor(tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager, deps: PromptEditorDeps) {
 		super(tui, theme, keybindings);
 		this.selectionEngine = new SelectionEngine(this);
 		this.deps = deps;
 		this.keybindingsManager = keybindings;
+		const attachments = deps.attachments;
+		if (!attachments || !deps.readClipboardImage) return;
+		// SAFETY: Pi's Editor routes cursor movement, wrapping and deletion through
+		// its private segment(). Wrapping it only merges registered chips into one
+		// segment; if a future Pi drops the method, chips degrade to plain text.
+		const host = this as unknown as {
+			segment?: (text: string, mode?: string) => Iterable<{ segment: string; index: number; input: string }>;
+			submitValue?: () => void;
+		};
+		const segment = host.segment;
+		if (typeof segment === "function") host.segment = (text, mode) => attachments.segment(text, segment.call(this, text, mode));
+		// SAFETY: Pi empties the draft in its private submitValue() before onSubmit.
+		// Counting here only marks the draft boundary; if a future Pi drops the
+		// method, a late read falls back to landing in the next draft.
+		const submitValue = host.submitValue;
+		if (typeof submitValue === "function") host.submitValue = () => { this.submittedDrafts += 1; submitValue.call(this); };
+		// Undefined until Pi installs its handler, so Pi's `if (!onPasteImage)`
+		// wiring still runs; afterwards every read returns the chip handler.
+		Object.defineProperty(this, "onPasteImage", {
+			configurable: true,
+			enumerable: true,
+			get: () => this.piPasteImage ? () => this.pasteImage() : undefined,
+			set: (handler: (() => void) | undefined) => { this.piPasteImage = handler; },
+		});
+	}
+
+	/** Registered image chips on `line`; the Vim adapter keeps NORMAL motions out of them. */
+	atomicSpans(line: string): Array<{ start: number; end: number }> {
+		return this.deps.attachments?.spans(line) ?? [];
+	}
+
+	/** Insert the clipboard image as a chip, or hand the paste to Pi. */
+	private pasteImage(): void {
+		const attachments = this.deps.attachments;
+		const read = this.deps.readClipboardImage;
+		if (!attachments || !read) { this.piPasteImage?.(); return; }
+		// The Windows clipboard read on WSL takes about a second; a repeated key
+		// press during it must not insert a second chip or a stray path.
+		if (this.pastingImage) return;
+		this.pastingImage = true;
+		void this.insertClipboardImage(attachments, read).finally(() => { this.pastingImage = false; });
+	}
+
+	private async insertClipboardImage(attachments: ImageAttachments, read: () => Promise<ClipboardImage | null>): Promise<void> {
+		const draft = this.submittedDrafts;
+		let image: ClipboardImage | null;
+		try { image = await read(); } catch { image = null; }
+		// A read that outlives this editor (session switch, quit) must not
+		// register bytes in the next session or write into a disposed prompt.
+		if (this.disposed) return;
+		// The draft this paste belonged to was already sent: neither attach the
+		// image to the next message nor run Pi's fallback into the new draft.
+		if (this.submittedDrafts !== draft) {
+			if (image) this.deps.notifyCompatibility?.("Image paste discarded: the message was sent before the clipboard finished reading. Paste again to attach it.");
+			return;
+		}
+		try {
+			if (!image) { this.piPasteImage?.(); return; }
+			const { token } = attachments.add(image);
+			const cursor = this.getCursor();
+			const line = this.getLines()[cursor.line] ?? "";
+			const before = cursor.col > 0 && !/\s/.test(line[cursor.col - 1] ?? "") ? " " : "";
+			const after = cursor.col < line.length && !/\s/.test(line[cursor.col] ?? "") ? " " : "";
+			this.insertTextAtCursor(`${before}${token}${after}`);
+			this.deps.requestRender();
+		} catch (error) {
+			// Never let a paste reject unhandled: Node 24 ends the process on it.
+			this.deps.notifyCompatibility?.(`Image paste failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
 	}
 
 	setAnimationPolicy(policy: AnimationPolicy): void {
 		if (this.animationPolicy === policy) return;
 		this.animationPolicy = policy;
-		this.stopPulse();
-		if (this.promptState === PROMPT_STATE.WORKING) this.startPulse();
+		this.stopWatchdog();
+		if (this.promptState === PROMPT_STATE.WORKING) this.startWatchdog();
 		this.deps.requestRender();
 	}
 
@@ -549,24 +726,32 @@ export class GentlePromptEditor extends CustomEditor {
 		this.deps.requestRender();
 	}
 
-	private startPulse(): void {
+	private startWatchdog(): void {
 		if (this.animationPolicy === "potato") return;
-		this.pulse = setInterval(() => {
+		const windowMs = this.deps.watchdogMs ?? SHELL_PULSE_WATCHDOG_MS;
+		this.lastRenderAt = this.deps.now();
+		this.watchdog = setInterval(() => {
+			// Render-driven petal (gentle-shell#994): streaming frames already
+			// advance the animation in render(), so under quality the watchdog
+			// stays silent unless no frame painted within its window. performance
+			// keeps its coarse cadence regardless of render traffic.
+			if (this.animationPolicy === "quality" && this.deps.now() - this.lastRenderAt < windowMs) return;
 			this.tick += 1;
+			this.lastRenderAt = this.deps.now();
 			this.deps.requestRender();
-		}, this.animationPolicy === "performance" ? 1000 : SHELL_PULSE_MS);
-		this.pulse.unref();
+		}, windowMs);
+		this.watchdog.unref();
 	}
 
 	setWorking(working: boolean): void {
 		this.promptState = working ? PROMPT_STATE.WORKING : PROMPT_STATE.IDLE;
-		this.stopPulse();
+		this.stopWatchdog();
 		if (!working) {
 			this.pendingEscapeCancelDeadline = undefined;
 		} else {
 			this.pendingIdleClearDeadline = undefined;
 			this.pendingIdleClearText = undefined;
-			this.startPulse();
+			this.startWatchdog();
 		}
 		this.deps.requestRender();
 	}
@@ -1053,6 +1238,13 @@ export class GentlePromptEditor extends CustomEditor {
 	}
 
 	render(width: number): string[] {
+		// Render-driven petal (gentle-shell#994): every frame the host already
+		// paints while working advances the animation for free, so no fast
+		// timer forces renders during streaming.
+		if (this.promptState === PROMPT_STATE.WORKING && this.animationPolicy === "quality") {
+			this.tick += 1;
+			this.lastRenderAt = this.deps.now();
+		}
 		const layout = resolvePromptLayout(width, cardStyle(), this.deps.bg);
 		this.floatMouseLayout = layout.background ? layout : undefined;
 		const inner = layout.nativeWidth;
@@ -1116,7 +1308,8 @@ export class GentlePromptEditor extends CustomEditor {
 	}
 
 	dispose(): void {
-		this.stopPulse();
+		this.disposed = true;
+		this.stopWatchdog();
 	}
 
 	private isPendingEscapeCancel(): boolean {
@@ -1131,13 +1324,62 @@ export class GentlePromptEditor extends CustomEditor {
 		);
 	}
 
-	private stopPulse(): void {
-		if (this.pulse) clearInterval(this.pulse);
-		this.pulse = undefined;
+	private stopWatchdog(): void {
+		if (this.watchdog) clearInterval(this.watchdog);
+		this.watchdog = undefined;
 		this.tick = 0;
 	}
 }
 
+const IMAGE_ATTACHMENTS_WIDGET_KEY = "gentle-shell-image-attachments";
+const IMAGE_PREVIEW_MAX_ROWS = 6;
+const IMAGE_PREVIEW_MAX_COLUMNS = 40;
+
+/** Unknown capabilities count as image-capable; Pi decides for its own models. */
+export function modelAcceptsImages(model: { input?: readonly string[] } | undefined): boolean {
+	return !model?.input || model.input.includes("image");
+}
+
+/**
+ * Lists the chips still in the draft above the prompt. Terminals with an image
+ * protocol (Kitty, iTerm2) get a thumbnail under each label; every other
+ * terminal, or a multiplexer that hides the protocol, gets the label alone.
+ */
+export function imageAttachmentsWidget(
+	attachments: ImageAttachments,
+	draft: () => string,
+	theme: { fg(color: string, text: string): string },
+	acceptsImages: () => boolean,
+	canDrawImages: () => boolean = () => getCapabilities().images !== null,
+) {
+	const previews = new Map<number, Image>();
+	return {
+		render(width: number): string[] {
+			const shown = attachments.referenced(draft());
+			for (const id of previews.keys()) if (!shown.some((attachment) => attachment.id === id)) previews.delete(id);
+			if (shown.length === 0) return [];
+			const draw = canDrawImages();
+			const warning = acceptsImages() ? "" : theme.fg("warning", " · not sent: the current model does not accept images");
+			const lines: string[] = [];
+			for (const attachment of shown) {
+				lines.push(truncateToWidth(`${theme.fg("accent", attachment.token)} ${theme.fg("dim", describeAttachment(attachment))}${warning}`, width));
+				if (!draw) continue;
+				let preview = previews.get(attachment.id);
+				if (!preview) {
+					preview = new Image(attachment.base64, attachment.mimeType, { fallbackColor: (text) => theme.fg("dim", text) },
+						{ maxWidthCells: IMAGE_PREVIEW_MAX_COLUMNS, maxHeightCells: IMAGE_PREVIEW_MAX_ROWS }, attachment.dimensions);
+					previews.set(attachment.id, preview);
+				}
+				lines.push(...preview.render(width));
+			}
+			return lines;
+		},
+		invalidate(): void {
+			for (const preview of previews.values()) preview.invalidate();
+		},
+	};
+}
+
 // Stable across extension module reloads; never infer ownership from a name.
 const PROMPT_OWNER = Symbol.for("gentle-pi.prompt-owner");
 type PromptFactory = NonNullable<ReturnType<ExtensionContext["ui"]["getEditorComponent"]>> & { [PROMPT_OWNER]?: boolean };
@@ -1145,7 +1387,7 @@ type PromptFactory = NonNullable<ReturnType<ExtensionContext["ui"]["getEditorCom
 function installPrompt(
 	ctx: ExtensionContext,
 	onCreated: (prompt: GentlePromptEditor) => void,
-	promptDeps: { now: () => number; doubleEscCancelEnabled: () => boolean; dispatchQueuedText: (text: string) => void; vimRuntimeVersion?: () => string | undefined },
+	promptDeps: { now: () => number; doubleEscCancelEnabled: () => boolean; dispatchQueuedText: (text: string) => void; vimRuntimeVersion?: () => string | undefined; attachments?: ImageAttachments; readClipboardImage?: () => Promise<ClipboardImage | null> },
 ): boolean {
 	const previous = ctx.ui.getEditorComponent() as PromptFactory | undefined;
 	if (previous && !previous[PROMPT_OWNER]) return false;
@@ -1162,10 +1404,12 @@ function installPrompt(
 			notifyCompatibility: (message) => ctx.ui.notify(message, "warning"),
 			tuiVersion: promptDeps.vimRuntimeVersion,
 			workingLabel: () => oddPhaseRegistry.label(ctx.sessionManager.getSessionId()),
+			attachments: promptDeps.attachments,
+			readClipboardImage: promptDeps.readClipboardImage,
 		});
 		// Pi's own docs require an explicit requestRender() after a state change
 		// (docs/tui.md: "Call tui.requestRender() after state changes"); no host
-		// re-render is implicitly guaranteed, and the WORKING pulse loop does not
+		// re-render is implicitly guaranteed, and the WORKING watchdog does not
 		// run at all under the "potato" animation policy. Register this session's
 		// redraw so a phase reported by the tool is visible immediately.
 		oddPhaseRegistry.setRenderRequest(ctx.sessionManager.getSessionId(), () => tui.requestRender());
@@ -1223,8 +1467,6 @@ const CHANGES_SHORTCUT_DEFAULT = "alt+g";
 const CHANGES_POLL_DEFAULT_MS = 2000;
 const GIT_TIMEOUT_MS = 5000;
 const COMMANDS_COMMAND_NAME = "gentle:commands";
-const OVERLAY_HEIGHT_RATIO = 0.8;
-const OVERLAY_MIN_ROWS = 8;
 
 export function shellGitRunner(cwd: string, env: NodeJS.ProcessEnv = process.env, run: typeof execFile = execFile, maxBuffer = Infinity): GitRunner {
 	// Pi exec cannot replace the inherited environment. Use argv directly and
@@ -1269,26 +1511,7 @@ const fileRevision = (root: string): FileRevision => async (path) => {
 	return `${info.size}:${info.mtimeMs}`;
 };
 
-export interface ExternalEditorHost {
-	stop(): void;
-	start(): void;
-	requestRender(force?: boolean): void;
-}
-
-export function openInExternalEditor(host: ExternalEditorHost, path: string, env: NodeJS.ProcessEnv = process.env, spawn: typeof spawnSync = spawnSync, cwd?: string): boolean {
-	const command = env.VISUAL || env.EDITOR;
-	if (!command) return false;
-	const [editor, ...editorArgs] = command.split(" ");
-	host.stop();
-	try {
-		spawn(editor, [...editorArgs, path], { cwd, stdio: "inherit", shell: process.platform === "win32" });
-	} finally {
-		host.start();
-		host.requestRender(true);
-	}
-	return true;
-}
-
+export { openInExternalEditor, type ExternalEditorHost } from "../lib/external-editor.ts";
 export function changesShortcut(env: NodeJS.ProcessEnv = process.env): string | undefined {
 	const value = env.GENTLE_PI_SHELL_CHANGES_KEY?.trim();
 	if (value === undefined) return CHANGES_SHORTCUT_DEFAULT;
@@ -1316,8 +1539,11 @@ function changesPollMs(env: NodeJS.ProcessEnv): number {
 const USAGE_FETCH_TIMEOUT_DEFAULT_MS = 10_000;
 const usageFetchTimeoutMs = (env: NodeJS.ProcessEnv): number => positiveMs(env.GENTLE_PI_SHELL_USAGE_TIMEOUT_MS, USAGE_FETCH_TIMEOUT_DEFAULT_MS);
 
+// The footer memo reads this every keystroke: tracker models store the
+// digest once per scan (lib/shell-changes.ts), so this is O(1); hand-built
+// models without a stored digest fall back to computing it here.
 function changesFingerprint(model: ChangesModel): string {
-	return model.files.map((file) => `${file.path}:${file.status}:${file.added}:${file.deleted}:${file.diffRevision ?? ""}:${file.countsUnavailable ?? ""}`).join("|");
+	return model.digest ?? changesDigest(model);
 }
 
 interface OverlayDeps {
@@ -1329,6 +1555,8 @@ interface OverlayDeps {
 }
 
 // The overlay polls each root's Git state while it is open; diffs load lazily.
+// Like Gentle Agents it takes the whole terminal, and the native fullscreen
+// wrapper keeps mouse dispatch on the view while it owns the keyboard.
 async function showChangesOverlay(ctx: ExtensionContext, deps: OverlayDeps): Promise<void> {
 	let host: ExternalEditorHost | undefined;
 	let view: WorktreeChangesView | undefined;
@@ -1346,19 +1574,25 @@ async function showChangesOverlay(ctx: ExtensionContext, deps: OverlayDeps): Pro
 				host = tui;
 				view = new WorktreeChangesView(deps.worktrees(), {
 					theme,
-					rows: () => Math.max(OVERLAY_MIN_ROWS, Math.floor(tui.terminal.rows * OVERLAY_HEIGHT_RATIO)),
+					rows: () => Math.max(0, tui.terminal.rows),
 					loadDiff: deps.loadDiff,
 					onOpen: (root, file) => close({ root, file }),
 					onRefresh: () => void refresh().catch(() => {}),
 					onClose: () => close(null),
 					requestRender: () => tui.requestRender(),
 				});
-				return view;
+				const interaction = createNativeFullscreenInteraction({ keyboardTarget: view, requestRender: () => tui.requestRender() });
+				interaction.addChild(view);
+				return interaction;
 			},
-			{ overlay: true, overlayOptions: { width: "92%", anchor: "center" } },
+			{ overlay: true, overlayOptions: { width: "100%", maxHeight: "100%", margin: 0, anchor: "center" } },
 		);
 		if (!chosen || !host) return;
-		if (!openInExternalEditor(host, chosen.file.path, process.env, spawnSync, chosen.root)) ctx.ui.notify("No editor configured. Set $VISUAL or $EDITOR.", "warning");
+		try {
+			if (!openInExternalEditor(host, chosen.file.path, process.env, spawnSync, chosen.root)) ctx.ui.notify("No editor configured. Set $VISUAL or $EDITOR.", "warning");
+		} catch (error) {
+			ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");
+		}
 	} finally {
 		clearInterval(poll);
 		view?.dispose();
@@ -1738,6 +1972,7 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 					onClose: () => withOverlayRepaint(tui, done)(null),
 					requestRender: () => tui.requestRender(),
 					scope: () => ({ providers: usageScope, failed: new Set(usageFailures) }),
+					gauge: () => gaugePaint(ctx),
 				});
 				// Open promptly: the panel draws whatever the store already holds
 				// while the forced refresh runs underneath it, and repaints when
@@ -1759,6 +1994,8 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 		});
 	}
 	let prompt: GentlePromptEditor | undefined;
+	// Images pasted into the current draft; emptied on every submit.
+	const imageAttachments = new ImageAttachments();
 	// Set by abortAndDispatchQueued via dispatchQueuedText when an Esc aborts
 	// a turn with a non-empty queue; sent exactly once, from agent_settled,
 	// once the aborted run has fully settled (issue #1218). Several aborts
@@ -1911,20 +2148,28 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 			const bottom = createShellBarComponent(pi, ctx, renderHost, theme, footerData, () => tracker.model.files.length, () => usage.get(ctx.model?.provider ?? ""), () => visualSettings);
 			// The Status card paints live session state that no event re-registers a
 			// part for: model, effort, context, cost, session name and extension
-			// statuses. The digest is what keeps the fullscreen memo honest, and it
-			// rebuilds the model exactly as the narrow bottom bar does every frame.
-			const footerModel = (): ShellBarModel => ({
-				...buildShellBarModel(pi, ctx, footerData, { dirty: tracker.model.files.length, usage: usage.get(ctx.model?.provider ?? ""), profile: deps.activeProfile(), jobs: runningJobs }),
-				changes: { files: tracker.model.files.length, added: tracker.model.added, deleted: tracker.model.deleted },
-				review,
+			// statuses. The digest is what keeps the fullscreen memo honest. Issue
+			// #1681: railDigest evaluates every rail's digest per keystroke, so both
+			// Status rails digest a cheap key and reuse the memoized model
+			// (createFooterStatusMemo).
+			const footerStatus = createFooterStatusMemo({
+				pi, ctx, footerData,
+				usage: () => usage.get(ctx.model?.provider ?? ""),
+				profile: () => deps.activeProfile(),
+				jobs: () => runningJobs,
+				review: () => review,
+				tracker: () => tracker,
+				visualSettings: () => visualSettings,
+				cardStyle: () => cardStyle(),
 			});
+			const footerModel = footerStatus.model;
 			// At narrow fullscreen widths only one status row paints: a top header
 			// suppresses the bottom bar in the layout, and otherwise the bottom bar
 			// takes over the header's data while the below-input header steps aside.
 			const statusOwner = () => narrowStatusOwner({ mode: (tui as TUI & { mode?: string }).mode, columns: tui.terminal?.columns ?? 0, statusPlacement: visualSettings.statusPlacement, headerPlacement: visualSettings.headerPlacement });
 			const statusCardVisible = () => Boolean(tui.terminal && tui.terminal.columns >= SIDEBAR_BREAKPOINT && sidebarState(tui).ownsHost?.() && visualSettings.statusPlacement !== "hidden");
 			const belowFloat = (width: number, statuses: boolean) => (tui as TUI & { mode?: string }).mode === "fullscreen"
-				? renderShellBelowInputFloat({ ...footerModel(), ...(statuses ? {} : { statuses: [] }), ...(statusCardVisible() ? { jobs: undefined } : {}) }, theme, width, usageShortcutKey, visualSettings, tracker.model)
+				? renderShellBelowInputFloat({ ...footerModel(), ...(statuses ? {} : { statuses: [] }), ...(statusCardVisible() ? { jobs: undefined } : {}) }, theme, width, usageShortcutKey, visualSettings, tracker.model, gaugePaint(ctx))
 				: undefined;
 			// Match sidebarPart's live paint ownership, including an unavailable rail.
 			const footerSuppressed = () => {
@@ -1935,7 +2180,7 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 			groupedChangesOwner = (width) => belowFloat(width, !footerSuppressed()) !== undefined;
 			const bottomBar = {
 				...bottom,
-				render: (width: number) => belowFloat(width, true)?.rows ?? (statusOwner() === STATUS_OWNER.BOTTOM ? renderShellBottomOnlyBar(footerModel(), theme, width, usageShortcutKey, visualSettings) : bottom.render(width)),
+				render: (width: number) => belowFloat(width, true)?.rows ?? (statusOwner() === STATUS_OWNER.BOTTOM ? renderShellBottomOnlyBar(footerModel(), theme, width, usageShortcutKey, visualSettings, undefined, gaugePaint(ctx)) : bottom.render(width)),
 				handleMouse(event: Parameters<NonNullable<SidebarRail["handleMouse"]>>[0]) {
 					if (footerSuppressed() || event.type !== "click" || event.button !== "left") return undefined;
 					const chrome = belowFloat(event.width, true);
@@ -1945,16 +2190,16 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 				},
 			};
 			const part = sidebarPart(tui, "footer", bottomBar, {
-				digest: () => JSON.stringify([footerModel(), tracker.model, visualSettings, cardStyle()]),
+				digest: () => footerStatus.key(),
 				render: (width) => renderShellSidebarBar(footerModel(), theme, width, visualSettings),
 				invalidate() {},
 			});
 			// The header row carries everything that ticks every frame (model,
 			// effort, context, cost, usage) plus session identity and the jobs count
 			// when Status is absent. Opaque statuses and working state stay excluded.
-			const headerBar = (width: number) => renderShellHeaderChrome(buildShellHeaderModel(footerModel(), !statusCardVisible() && (statusOwner() === STATUS_OWNER.HEADER || visualSettings.statusPlacement === "hidden")), theme, width, usageShortcutKey, visualSettings);
+			const headerBar = (width: number) => renderShellHeaderChrome(buildShellHeaderModel(footerModel(), !statusCardVisible() && (statusOwner() === STATUS_OWNER.HEADER || visualSettings.statusPlacement === "hidden")), theme, width, usageShortcutKey, visualSettings, gaugePaint(ctx));
 			const disposeHeader = sidebarHeader(tui, {
-				digest: () => JSON.stringify([footerModel(), tracker.model, visualSettings, cardStyle()]),
+				digest: () => footerStatus.key(),
 				render: (width) => headerBar(width).rows,
 				invalidate() {},
 				handleMouse(event) {
@@ -2003,8 +2248,15 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 				prompt.setAnimationPolicy(animationPolicy);
 				prompt.setVimPolicy(vimPolicy);
 			},
-			{ now: () => deps.now(), doubleEscCancelEnabled: () => doubleEscCancelPolicy === "on", dispatchQueuedText: (text) => { pendingQueuedText = pendingQueuedText === undefined ? text : `${pendingQueuedText}\n\n${text}`; }, vimRuntimeVersion: deps.vimRuntimeVersion },
+			{ now: () => deps.now(), doubleEscCancelEnabled: () => doubleEscCancelPolicy === "on", dispatchQueuedText: (text) => { pendingQueuedText = pendingQueuedText === undefined ? text : `${pendingQueuedText}\n\n${text}`; }, vimRuntimeVersion: deps.vimRuntimeVersion, attachments: imageAttachments, readClipboardImage: () => (deps.readClipboardImage ?? readClipboardImage)() },
 		);
+		imageAttachments.clear();
+		ctx.ui.setWidget(IMAGE_ATTACHMENTS_WIDGET_KEY, ownsPrompt
+			// Kitty re-sends a full image block whenever content above it moves, so
+			// thumbnails show only while idle; while the agent streams, labels only.
+			? (_tui, theme) => imageAttachmentsWidget(imageAttachments, () => prompt?.getText() ?? "", theme, () => modelAcceptsImages(ctx.model),
+				() => getCapabilities().images !== null && ctx.isIdle())
+			: undefined);
 		// Hide native feedback only when our petal replaces it. Native transcript
 		// thinking blocks remain Pi-owned; this changes only the supported loader UI.
 		// Inside Herdr the row stays: its native Pi detection reads it.
@@ -2020,6 +2272,20 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 		shown = "";
 		applyChanges(ctx, tracker.model);
 	});
+	// Chips still in the submitted draft travel as real image attachments, so
+	// the model sees the image without calling `read` on a temp-file path.
+	pi.on("input", (event, ctx) => {
+		if (event.source !== "interactive" || imageAttachments.size === 0) return { action: "continue" };
+		// The editor may already hold the next draft (a prompt Pi queued during
+		// compaction): its chips stay registered for their own submit.
+		const submitted = imageAttachments.submit(event.text, modelAcceptsImages(ctx.model), prompt?.getText() ?? "");
+		if (!submitted) return { action: "continue" };
+		if (submitted.omitted > 0 && ctx.hasUI) {
+			const count = submitted.omitted === 1 ? "1 pasted image was" : `${submitted.omitted} pasted images were`;
+			ctx.ui.notify(`${count} not sent: the current model does not accept images. Switch to a vision model and paste again.`, "warning");
+		}
+		return { action: "transform", text: submitted.text, images: [...(event.images ?? []), ...submitted.images] };
+	});
 	pi.on("session_shutdown", (_event, ctx) => {
 		closeCustomize?.();
 		if (review) {
@@ -2035,6 +2301,8 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 		oddPhaseRegistry.clear(ctx.sessionManager.getSessionId());
 		oddPhaseRegistry.clearRenderRequest(ctx.sessionManager.getSessionId());
 		pendingQueuedText = undefined;
+		imageAttachments.clear();
+		ctx.ui.setWidget(IMAGE_ATTACHMENTS_WIDGET_KEY, undefined);
 		prompt?.dispose();
 		prompt = undefined;
 		if ((ctx.ui.getEditorComponent() as PromptFactory | undefined)?.[PROMPT_OWNER]) {
@@ -2054,10 +2322,14 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 		applyChanges(ctx, model);
 		// A failed root scan is unknown, never clean: say so whenever one failed.
 		const failed = tracker.failedRoots.length;
+		const unborn = tracker.unbornRoots.length;
 		const roots = tracker.scannedRootCount;
 		if (model.files.length === 0) {
 			if (failed > 0 && failed === roots) ctx.ui.notify(`Could not read Git status for ${failed} ${failed === 1 ? "root" : "roots"}; uncommitted changes are unknown.`, "error");
 			else if (failed > 0) ctx.ui.notify(`No uncommitted changes in the roots Git could read; Git status failed for ${failed} of ${roots} roots.`, "warning");
+			else if (unborn > 0) ctx.ui.notify(unborn === roots
+				? `No commits yet in ${unborn === 1 ? "this session's repository" : "any root"} — make a commit to start tracking changes.`
+				: `No uncommitted changes; ${unborn} of ${roots} roots have no commits yet, so they are not tracked.`, "info");
 			else ctx.ui.notify("No uncommitted changes in this session's repository or its subagents' worktrees.", "info");
 			return;
 		}
@@ -2254,19 +2526,21 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 					await refreshYolo();
 				},
 			});
-			for (const mode of ["normal", "auto", "yolo"] as const) rows.push({
+			for (const mode of ["normal", "auto", "yolo", "super-yolo"] as const) rows.push({
 				category,
 				label: () => `Session permissions: ${mode.toUpperCase()}${mode === "auto" ? " (beta)" : ""}${permissionDisplay === mode ? " (current)" : ""}`,
 				preview: () => ({ title: "Permissions · current session", sample: mode === "auto"
 					? "independent session-model action checks · extra inference cost · hard safety and native consent remain"
-					: mode === "yolo" ? "ordinary scoped delivery permission · destructive confirmations remain" : "normal checks · overrides an elevated global default" }),
+					: mode === "yolo" ? "ordinary scoped delivery permission · destructive confirmations remain"
+					: mode === "super-yolo" ? "no permission prompts · only private-path protection (.env, keys, secrets) remains"
+					: "normal checks · overrides an elevated global default" }),
 				action: async () => {
 					if (closed) return;
 					if (!adapter?.setMode || !await adapter.setMode(mode)) ctx.ui.notify("Session mode unchanged — live primary UI unavailable or changed.", "warning");
 					await refreshYolo();
 				},
 			});
-			for (const mode of ["normal", "auto", "yolo"] as const) rows.push({
+			for (const mode of ["normal", "auto", "yolo", "super-yolo"] as const) rows.push({
 				category,
 				label: () => `Default permissions: ${mode.toUpperCase()}${mode === "auto" ? " (beta)" : ""}${permissionDefault === mode ? " (saved)" : ""}`,
 				preview: () => ({ title: "Permissions · user-global default", sample: `New primary sessions start in ${mode.toUpperCase()}; current session stays unchanged. ${mode === "auto" ? "Additional classifier inference uses the session model; usage is separate." : "Independent safety and consent remain."}` }),