@oh-my-pi/pi-tui 18.11.3 → 18.12.0

package/src/chat/tool-execution.ts

@@ -8,7 +8,7 @@ import { Text } from "../components/text";
 import { getImageDimensions, ImageProtocol, imageFallback, TERMINAL } from "../terminal-capabilities";
 import { type Component, Container, type TUI } from "../tui";
 import { truncateToWidth } from "../utils";
-import { getProjectDir, isRecord, logger, sanitizeText } from "@oh-my-pi/pi-utils";
+import { getProjectDir, isRecord, logger, sanitizeText, sanitizeTextDeep } from "@oh-my-pi/pi-utils";
 import type { Theme } from "../theme/theme";
 import { ensureThemeSync, getThemeEpoch, theme } from "../theme/theme";
 import {
@@ -420,6 +420,8 @@ export class ToolExecutionComponent extends Container {
 		isError?: boolean;
 		details?: unknown;
 	};
+	// Machine paths remain verbatim; only #result.details is handed to display renderers.
+	#rawDetails: unknown;
 	// Edit preview state
 	#editMode?: EditMode;
 	#editDiffPreview?: PerFileDiffPreview[];
@@ -632,7 +634,11 @@ export class ToolExecutionComponent extends Container {
 		const partialResultPainted = this.#partialResultShapePainted;
 		this.#firstResultViewportRepaintShapePainted = false;
 		this.#partialResultShapePainted = false;
-		this.#result = result;
+		this.#rawDetails = result.details;
+		// Renderers receive sanitized details for display; raw paths are available
+		// separately for links and media through the built-in render context.
+		const details = sanitizeTextDeep(result.details);
+		this.#result = details === result.details ? result : { ...result, details };
 		this.#resultVersion++;
 		this.#blockVersion++;
 		this.#isPartial = isPartial;
@@ -1251,7 +1257,7 @@ export class ToolExecutionComponent extends Container {
 	#nativeResultImages(body: readonly NativeChild[] | undefined): NativeNode[] {
 		if (!this.#result || !this.#showImages) return [];
 		const shown = shownMedia(body);
-		const mediaPath = readMediaPath(this.#result.details);
+		const mediaPath = readMediaPath(this.#rawDetails);
 		if (mediaPath && shown.paths.has(mediaPath)) return [];
 		const images: NativeNode[] = [];
 		this.#getAllImageBlocks().forEach((image, index) => {
@@ -1558,6 +1564,10 @@ export class ToolExecutionComponent extends Container {
 				this.#contentBox.clear();
 
 				const renderContext = this.#buildRenderContext();
+				const rawPerFileResults =
+					isRecord(this.#rawDetails) && Array.isArray(this.#rawDetails.perFileResults)
+						? this.#rawDetails.perFileResults
+						: undefined;
 				this.#renderState.renderContext = renderContext;
 
 				for (let i = 0; i < perFileResults.length; i++) {
@@ -1569,9 +1579,13 @@ export class ToolExecutionComponent extends Container {
 					}
 					const fileBox = new Box(0, 0);
 					try {
+						const fileOptions = {
+							...this.#renderState,
+							renderContext: { ...renderContext, rawDetails: rawPerFileResults?.[i] },
+						};
 						const resultComponent = renderer.renderResult(
 							{ content: [], details: fileResult, isError: fileResult.isError },
-							this.#renderState,
+							fileOptions,
 							theme,
 						);
 						if (resultComponent) {
@@ -1695,7 +1709,7 @@ export class ToolExecutionComponent extends Container {
 
 		if (this.#result) {
 			const imageBlocks = this.#getAllImageBlocks();
-			const sourcePath = readMediaPath(this.#result.details);
+			const sourcePath = readMediaPath(this.#rawDetails);
 
 			for (let i = 0; i < imageBlocks.length; i++) {
 				const img = imageBlocks[i];
@@ -1802,6 +1816,9 @@ export class ToolExecutionComponent extends Container {
 			return Math.max(1, Math.min(maxSeconds, value));
 		};
 
+		if (this.#renderer && !this.#tool?.renderResult && this.#rawDetails !== undefined) {
+			context.rawDetails = this.#rawDetails;
+		}
 		if (this.#toolName === "bash") {
 			// Bash needs render context even before a result exists. The renderer uses the pending-call args
 			// plus this context to keep the inline command preview visible while tool-call JSON is still streaming.
@@ -1882,7 +1899,7 @@ export class ToolExecutionComponent extends Container {
 					const dims = img.data ? (getImageDimensions(img.data, mimeType) ?? undefined) : undefined;
 					const placeholder = imageFallback(mimeType, dims);
 					return img.data
-						? linkedImageText(placeholder, { data: img.data, mimeType }, readMediaPath(this.#result?.details))
+						? linkedImageText(placeholder, { data: img.data, mimeType }, readMediaPath(this.#rawDetails))
 						: placeholder;
 				})
 				.join("\n");

package/src/components/image.ts

@@ -4,6 +4,7 @@ import {
 	encodeSixelNow,
 	getCellDimensions,
 	getImageDimensions,
+	getTerminalBackgroundColor,
 	type ImageDimensions,
 	ImageProtocol,
 	imageFallback,
@@ -41,6 +42,13 @@ export interface ImageOptions {
 	requestRender?: () => void;
 }
 
+interface SixelEncode {
+	widthPx: number;
+	heightPx: number;
+	backgroundRgb: number;
+	sequence?: string | null;
+}
+
 /** Renders in progress whose rows are bound for native scrollback. */
 let scrollbackRenderDepth = 0;
 
@@ -655,6 +663,7 @@ export class Image implements Component {
 	#cachedImageProtocol: typeof TERMINAL.imageProtocol = null;
 	#cachedCellWidthPx = 0;
 	#cachedCellHeightPx = 0;
+	#cachedSixelBackground: number | undefined;
 	#cachedKittyUnicodePlaceholders = false;
 	#cachedLinked = false;
 	// Tallest graphic placement this image has rendered. The text fallback
@@ -663,8 +672,8 @@ export class Image implements Component {
 	#renderedGraphicRows = 0;
 	/** Described node and the link policy it was built under (an `off` switch drops its `href`). */
 	#native?: { linked: boolean; node: NativeNode };
-	/** Newest SIXEL encode: its target size and, once settled, the sequence (`null` on failure). */
-	#sixel?: { widthPx: number; heightPx: number; sequence?: string | null };
+	/** Newest SIXEL encode: target size, compositing background, and settled sequence. */
+	#sixel?: SixelEncode;
 
 	constructor(
 		base64Data: string,
@@ -704,33 +713,38 @@ export class Image implements Component {
 	}
 
 	/**
-	 * SIXEL sequence for a target size. A new size starts the encode off the JS
+	 * SIXEL sequence for a target size and background. A change starts the encode off the JS
 	 * thread and answers `undefined` until it settles; the settled encode
 	 * invalidates the cached lines and requests a repaint. A render bound for
 	 * scrollback cannot wait, so it encodes synchronously.
 	 */
-	#sixelSequence(widthPx: number, heightPx: number): string | null | undefined {
+	#sixelSequence(widthPx: number, heightPx: number, backgroundRgb: number): string | null | undefined {
 		const current = this.#sixel;
-		const sameSize = current !== undefined && current.widthPx === widthPx && current.heightPx === heightPx;
-		if (sameSize && current.sequence !== undefined) return current.sequence;
+		const sameInput =
+			current !== undefined &&
+			current.widthPx === widthPx &&
+			current.heightPx === heightPx &&
+			current.backgroundRgb === backgroundRgb;
+		if (sameInput && current.sequence !== undefined) return current.sequence;
 		if (scrollbackRenderDepth > 0) {
 			// Replacing the entry makes a still-pending async encode settle as stale.
-			const sequence = encodeSixelNow(this.#base64Data, widthPx, heightPx);
-			this.#sixel = { widthPx, heightPx, sequence };
+			const sequence = encodeSixelNow(this.#base64Data, widthPx, heightPx, backgroundRgb);
+			this.#sixel = { widthPx, heightPx, backgroundRgb, sequence };
 			return sequence;
 		}
-		if (sameSize) return undefined;
-		const request: { widthPx: number; heightPx: number; sequence?: string | null } = { widthPx, heightPx };
+		if (sameInput) return undefined;
+		const request: SixelEncode = { widthPx, heightPx, backgroundRgb };
 		this.#sixel = request;
 		const settle = (sequence: string | null): void => {
 			request.sequence = sequence;
-			if (this.#sixel !== request) return;
+			if (this.#sixel !== request || getTerminalBackgroundColor() !== backgroundRgb) return;
 			this.invalidate();
 			if (this.#options.requestRender) this.#options.requestRender();
 			else this.#budget?.requestRender();
 		};
-		encodeSixelAsync(new Uint8Array(Buffer.from(this.#base64Data, "base64")), widthPx, heightPx).then(settle, () =>
-			settle(null),
+		encodeSixelAsync(new Uint8Array(Buffer.from(this.#base64Data, "base64")), widthPx, heightPx, backgroundRgb).then(
+			settle,
+			() => settle(null),
 		);
 		return undefined;
 	}
@@ -768,6 +782,7 @@ export class Image implements Component {
 		const hasProtocol = imageProtocol != null;
 		const cellDimensions = getCellDimensions();
 		const kittyUnicodePlaceholders = getKittyGraphics().unicodePlaceholders;
+		const sixelBackground = imageProtocol === ImageProtocol.Sixel ? getTerminalBackgroundColor() : undefined;
 		// observe() must run on every pass — even a cache hit — so the image keeps
 		// its display-order slot in the budget. Only graphics-capable frames count
 		// toward (and are demoted by) the budget; without a protocol every image is
@@ -789,6 +804,7 @@ export class Image implements Component {
 			this.#cachedImageProtocol === imageProtocol &&
 			this.#cachedCellWidthPx === cellDimensions.widthPx &&
 			this.#cachedCellHeightPx === cellDimensions.heightPx &&
+			this.#cachedSixelBackground === sixelBackground &&
 			this.#cachedKittyUnicodePlaceholders === kittyUnicodePlaceholders &&
 			// The text fallback embeds a link only under an enabled hyperlink policy.
 			this.#cachedLinked === linked &&
@@ -813,7 +829,7 @@ export class Image implements Component {
 				maxHeightCells: this.#options.maxHeightCells,
 				imageId: this.#imageId,
 				includeTransmit: needsTransmit,
-				sixel: (widthPx, heightPx) => this.#sixelSequence(widthPx, heightPx),
+				sixel: (widthPx, heightPx) => this.#sixelSequence(widthPx, heightPx, sixelBackground!),
 			});
 
 			if (result?.transmit && this.#imageId != null && this.#budget !== undefined) {
@@ -861,6 +877,7 @@ export class Image implements Component {
 		this.#cachedImageProtocol = imageProtocol;
 		this.#cachedCellWidthPx = cellDimensions.widthPx;
 		this.#cachedCellHeightPx = cellDimensions.heightPx;
+		this.#cachedSixelBackground = sixelBackground;
 		this.#cachedKittyUnicodePlaceholders = kittyUnicodePlaceholders;
 		this.#cachedLinked = linked;
 

package/src/render/hanging-wrap.ts

@@ -17,7 +17,7 @@ export function wrapTreeLine(line: string, width: number, theme: Theme): string[
 		const index = line.indexOf(marker);
 		if (index < 0) continue;
 		const before = line.slice(0, index);
-		if (!/^[ │]*$/.test(Bun.stripANSI(before))) continue;
+		if (!/^ *$/.test(Bun.stripANSI(before).replaceAll(theme.tree.vertical, ""))) continue;
 		const end = index + marker.length + 1;
 		if (line[end - 1] !== " ") continue;
 		const connectorWidth = visibleWidth(connector);
@@ -29,3 +29,30 @@ export function wrapTreeLine(line: string, width: number, theme: Theme): string[
 	}
 	return undefined;
 }
+
+const SGR = /\x1b\[[0-9;]*m/y;
+
+/** End of the leading run of spaces, `vertical` guides and SGR escapes that a tree detail row hangs beneath. */
+function guideRunEnd(line: string, vertical: string): number {
+	let index = 0;
+	while (index < line.length) {
+		if (line[index] === " ") {
+			index++;
+		} else if (vertical && line.startsWith(vertical, index)) {
+			index += vertical.length;
+		} else {
+			SGR.lastIndex = index;
+			if (!SGR.test(line)) break;
+			index = SGR.lastIndex;
+		}
+	}
+	return index;
+}
+
+/** Hang a tree row beneath its connector, or a connector-less detail row beneath its guide rails. */
+export function wrapGuidedLine(line: string, width: number, theme: Theme): string[] {
+	const tree = wrapTreeLine(line, width, theme);
+	if (tree) return tree;
+	const prefix = line.slice(0, guideRunEnd(line, theme.tree.vertical));
+	return wrapPrefixedLine(prefix, prefix, line.slice(prefix.length), width);
+}

package/src/render/render-utils.ts

@@ -233,15 +233,29 @@ export function getPreviewLines(text: string, maxLines: number, maxLineLen: numb
 	return lines.slice(0, maxLines).map(l => truncateToWidth(l.trim(), maxLineLen, ellipsis));
 }
 
+/** Collapse a possibly multi-line string into one line; whitespace runs (tabs included) become one space. */
+export function flattenLine(text: string): string {
+	return text.replace(/\s+/g, " ").trim();
+}
+
 /**
  * Collapse a possibly multi-line string into a single line, then truncate it to
  * `maxWidth` display cells. {@link truncateToWidth} alone caps width but
  * newlines are zero-width, so multi-line content (markdown briefs, tool args,
  * provider errors) would otherwise spill a single status row across several
- * visual lines. Whitespace runs collapse to one space, so tabs are handled too.
+ * visual lines.
  */
 export function previewLine(text: string, maxWidth: number, ellipsis?: Ellipsis): string {
-	return truncateToWidth(text.replace(/\s+/g, " ").trim(), maxWidth, ellipsis);
+	return truncateToWidth(flattenLine(text), maxWidth, ellipsis);
+}
+
+/**
+ * Clip a result row to `maxWidth` only while collapsed. Expanded rows stay whole
+ * so the frame wraps them: the expand key ({@link formatExpandHint}) must reveal
+ * text, not re-clip it.
+ */
+export function clipCollapsed(text: string, maxWidth: number, expanded: boolean | undefined): string {
+	return expanded ? text : truncateToWidth(text, maxWidth);
 }
 
 // =============================================================================

package/src/status-line/component.ts

@@ -1977,6 +1977,7 @@ export class StatusLineComponent<TSession extends StatusLineSession = StatusLine
 	 * cadence while a late successful fetch can still refresh the cached segment.
 	 */
 	refreshUsageInBackground(): void {
+		if (this.#disposed) return;
 		const now = Date.now();
 		const session = this.session;
 		const usageContextKey = this.#getUsageContextKey(session);

package/src/status-line/segments.ts

@@ -216,7 +216,7 @@ const piSegment: StatusLineSegment = {
 		// Brand fg fades between dim gray (idle) and the accent (working) across
 		// turn edges; the component samples the tween into `brandFgAnsi`.
 		const fgAnsi = ctx.brandFgAnsi ?? theme.getFgAnsi("dim");
-		const profile = getActiveProfile();
+		const profile = ctx.options.pi?.showProfile === false ? undefined : getActiveProfile();
 		// While a turn runs the brand icon becomes a braille spinner plus a
 		// whole-unit turn timer (port of rust omp's status-band active brand).
 		// No trailing pad: the group renderer owns inter-segment spacing, so a
@@ -230,14 +230,15 @@ const piSegment: StatusLineSegment = {
 	describe(ctx) {
 		if (ctx.focusedAgentId) return segView([span(ctx.focusedAgentId, "warning")], "ghost", "warning");
 		// The dock's working row owns activity natively: the brand stays still.
-		const profile = getActiveProfile();
+		const profile = ctx.options.pi?.showProfile === false ? undefined : getActiveProfile();
 		return segView(profile ? [span(profile, "muted")] : [], "omp", "muted");
 	},
 };
 /**
  * Brand glyph tagged with the active named profile (`π-work`) so sessions from
  * different profiles are distinguishable at a glance; the bare glyph for the
- * default profile. The tag stays put while the glyph slot animates.
+ * default profile or with `segmentOptions.pi.showProfile: false`. The tag
+ * stays put while the glyph slot animates.
  */
 function brandMark(glyph: string, profile: string | undefined): string {
 	if (!profile) return glyph;

package/src/status-line/types.ts

@@ -36,6 +36,7 @@ export interface CollabStatus {
 }
 
 export interface StatusLineSegmentOptions {
+	pi?: { showProfile?: boolean };
 	model?: { showThinkingLevel?: boolean };
 	path?: { abbreviate?: boolean; maxLength?: number; stripWorkPrefix?: boolean };
 	git?: { showBranch?: boolean; showStaged?: boolean; showUnstaged?: boolean; showUntracked?: boolean };

package/src/terminal-capabilities.ts

@@ -12,16 +12,35 @@ import {
 } from "./kitty-graphics";
 import {
 	isInsideTerminalMultiplexer,
+	isTerminalBackgroundQueryTrusted,
 	routeTerminalMultiplexerNotification,
 	terminalMultiplexerForTerm,
 	terminalMultiplexerSessions,
 } from "./terminal-multiplexer";
 import { resolveTmuxClientTerminalNames, wrapTmuxPassthroughIfNeeded } from "./tmux";
+import { detectTerminalBackground } from "./theme/theme";
 import type { HangulCompatibilityJamoWidth } from "./utils";
 
 export * from "./terminal-multiplexer";
 export { wrapTmuxPassthrough } from "./tmux";
 
+/** Last valid OSC 11 background, packed as 0xRRGGBB. */
+let terminalBackgroundColor: number | undefined;
+
+/**
+ * Trusted terminal background when reported; otherwise black for detected dark
+ * appearance or white for detected light appearance, using theme auto-detection.
+ */
+export function getTerminalBackgroundColor(): number {
+	if (isTerminalBackgroundQueryTrusted() && terminalBackgroundColor !== undefined) return terminalBackgroundColor;
+	return detectTerminalBackground() === "light" ? 0xffffff : 0x000000;
+}
+
+/** Store an OSC 11 background, or reset to appearance detection (also for tests). */
+export function setTerminalBackgroundColor(color: number | undefined): void {
+	terminalBackgroundColor = color;
+}
+
 export enum ImageProtocol {
 	Kitty = "\x1b_G",
 	Iterm2 = "\x1b]1337;File=",
@@ -1249,9 +1268,14 @@ export function getImageDimensions(base64Data: string, mimeType: string): ImageD
  * thread; `null` when the encode fails. For output that cannot wait for an
  * off-thread encode.
  */
-export function encodeSixelNow(base64Data: string, widthPx: number, heightPx: number): string | null {
+export function encodeSixelNow(
+	base64Data: string,
+	widthPx: number,
+	heightPx: number,
+	backgroundRgb = getTerminalBackgroundColor(),
+): string | null {
 	try {
-		return encodeSixel(new Uint8Array(Buffer.from(base64Data, "base64")), widthPx, heightPx);
+		return encodeSixel(new Uint8Array(Buffer.from(base64Data, "base64")), widthPx, heightPx, backgroundRgb);
 	} catch {
 		return null;
 	}

package/src/terminal-multiplexer.ts

@@ -67,6 +67,20 @@ export function terminalMultiplexerSessions(
 	return TERMINAL_MULTIPLEXERS.filter(multiplexer => multiplexer.isInside(env));
 }
 
+/**
+ * Whether OSC 11 background replies are trusted on this platform. Any active
+ * session with `backgroundQueryBrokenOn` matching the platform makes the entire
+ * path untrusted; TERM-only classification does not identify an active session.
+ */
+export function isTerminalBackgroundQueryTrusted(
+	env: NodeJS.ProcessEnv = Bun.env,
+	platform: NodeJS.Platform = process.platform,
+): boolean {
+	return !TERMINAL_MULTIPLEXERS.some(
+		multiplexer => multiplexer.isInside(env) && multiplexer.backgroundQueryBrokenOn?.includes(platform),
+	);
+}
+
 /**
  * The multiplexer TERM names, whether or not its session markers survived.
  * This is classification's TERM fallback; session markers are not consulted.

package/src/terminal.ts

@@ -25,6 +25,7 @@ import {
 	NotifyProtocol,
 	setCellDimensions,
 	setOsc99Supported,
+	setTerminalBackgroundColor,
 	setTerminalGlyphProtocol,
 	TERMINAL,
 } from "./terminal-capabilities";
@@ -1125,6 +1126,8 @@ export class ProcessTerminal implements Terminal {
 		// Own stdout: out-of-band writers route through this terminal, and the
 		// emergency restore finds it on crash.
 		setActiveTerminal(this);
+		// RGB belongs to this ownership session, including deferred-input prepaint.
+		setTerminalBackgroundColor(undefined);
 		terminalEverStarted = true;
 		// Own the blocking write(2) on a pump thread (unix TTYs only). A stale
 		// prebuilt natives module without the export falls back to direct writes.
@@ -2041,7 +2044,11 @@ export class ProcessTerminal implements Terminal {
 			const max = 16 ** hex.length - 1;
 			return max > 0 ? value / max : 0;
 		};
-		const luminance = 0.299 * normalize(rHex) + 0.587 * normalize(gHex) + 0.114 * normalize(bHex);
+		const r = normalize(rHex);
+		const g = normalize(gHex);
+		const b = normalize(bHex);
+		setTerminalBackgroundColor((Math.round(r * 255) << 16) | (Math.round(g * 255) << 8) | Math.round(b * 255));
+		const luminance = 0.299 * r + 0.587 * g + 0.114 * b;
 		const mode: TerminalAppearance = luminance < 0.5 ? "dark" : "light";
 		const changed = mode !== this.#appearance;
 		this.#appearance = mode;
@@ -2313,11 +2320,13 @@ export class ProcessTerminal implements Terminal {
 		// Suppress observer/timer callbacks before any teardown can yield or throw.
 		this.#active = false;
 		this.#inputDeferred = false;
-		if (this.#headless) return;
 		// Release stdout ownership (out-of-band writers and emergency cleanup)
+		// before headless/teardown exits, without disturbing another owner's RGB.
 		if (getActiveTerminal() === this) {
 			setActiveTerminal(null);
+			setTerminalBackgroundColor(undefined);
 		}
+		if (this.#headless) return;
 
 		// Release terminal ownership of fd 2 first so external programs,
 		// suspend, and shutdown see the real stderr even if a later teardown

package/src/theme/theme.ts

@@ -5,7 +5,7 @@ import type { Terminal, TerminalAppearance } from "../terminal";
 import { colorLuma } from "@oh-my-pi/pi-utils/color";
 import { getCustomThemesDir } from "@oh-my-pi/pi-utils/dirs";
 import * as logger from "@oh-my-pi/pi-utils/logger";
-import { terminalMultiplexerSessions } from "../terminal-multiplexer";
+import { isTerminalBackgroundQueryTrusted } from "../terminal-multiplexer";
 import { setActiveSymbolTheme } from "./active-symbols";
 import { ansi256ToHex, resolveThemeColors, resolveVarRefs } from "./color";
 import {
@@ -50,18 +50,28 @@ var terminalReportedAppearance: "dark" | "light" | undefined;
 /** Appearance reported by the macOS fallback observer, or undefined if not yet available. */
 var macOSReportedAppearance: "dark" | "light" | undefined;
 
-function shouldUseMacOSAppearanceFallback(): boolean {
-	// Some multiplexers break OSC 11 passthrough on some platforms (Zellij on
-	// macOS), so terminal-derived appearance cannot be trusted there. Fall back
-	// to host macOS appearance without letting it override valid terminal
-	// signals elsewhere.
-	const platform = process.platform;
-	return terminalMultiplexerSessions().some(multiplexer => multiplexer.backgroundQueryBrokenOn?.includes(platform));
+const backgroundFallbackListeners = new Set<() => void>();
+
+/**
+ * Subscribe to native fallback appearance changes independently of theme changes.
+ * Consumers must re-check the effective background: COLORFGBG can override it.
+ */
+export function onTerminalBackgroundFallbackChange(callback: () => void): () => void {
+	backgroundFallbackListeners.add(callback);
+	return () => {
+		backgroundFallbackListeners.delete(callback);
+	};
 }
 
-function detectTerminalBackground(): "dark" | "light" {
+/**
+ * Detect appearance from trusted OSC 11 reports, then COLORFGBG, then native
+ * macOS appearance only on known-broken multiplexer background-query paths.
+ * Defaults to dark when none of those signals is available.
+ */
+export function detectTerminalBackground(): "dark" | "light" {
+	const backgroundQueryTrusted = isTerminalBackgroundQueryTrusted();
 	// Tier 1: terminal-reported appearance from OSC 11 luminance.
-	if (!shouldUseMacOSAppearanceFallback() && terminalReportedAppearance) {
+	if (backgroundQueryTrusted && terminalReportedAppearance) {
 		return terminalReportedAppearance;
 	}
 
@@ -76,7 +86,7 @@ function detectTerminalBackground(): "dark" | "light" {
 	}
 
 	// Tier 3: host macOS appearance for known-broken terminal paths only.
-	if (shouldUseMacOSAppearanceFallback()) {
+	if (!backgroundQueryTrusted) {
 		const macAppearance = macOSReportedAppearance ?? detectMacOSAppearance();
 		if (macAppearance) return macAppearance;
 	}
@@ -214,14 +224,14 @@ export async function initTheme(
 		assignTheme(await loadTheme(name, getCurrentThemeOptions()));
 		if (enableWatcher) {
 			await startThemeWatcher();
-			startSigwinchListener();
 		}
 	} catch (err) {
 		logger.debug("Theme loading failed, falling back to dark theme", { error: String(err) });
 		currentThemeName = "dark";
 		assignTheme(await loadTheme("dark", getCurrentThemeOptions()));
-		// Don't start watcher for fallback theme
+		// Skip file watching for the fallback theme, not appearance tracking.
 	}
+	if (enableWatcher) startSigwinchListener();
 }
 
 export async function setTheme(
@@ -239,6 +249,14 @@ export async function setTheme(
 		assignTheme(loadedTheme);
 		if (enableWatcher) {
 			await startThemeWatcher();
+			// startThemeWatcher() calls stopThemeWatcher(), which tears down
+			// the SIGWINCH handler and the macOS appearance observer that
+			// feeds the SIXEL background fallback. Restart it like initTheme()
+			// does so a runtime theme change does not silence fallback
+			// background repaints. Without this, `setTheme(name, true)` after
+			// startup would leave the SIXEL repaint path dead until the next
+			// process restart.
+			startSigwinchListener();
 		}
 		notifyThemeChange();
 		return { success: true };
@@ -667,12 +685,26 @@ var macObserver: { stop(): void } | undefined;
 
 function startMacAppearanceObserver(): void {
 	stopMacAppearanceObserver();
-	if (!shouldUseMacOSAppearanceFallback()) return;
+	if (isTerminalBackgroundQueryTrusted()) return;
 	try {
 		macOSReportedAppearance = detectMacOSAppearance() ?? undefined;
 		macObserver = MacAppearanceObserver.start((err, appearance) => {
 			if (!err && (appearance === "dark" || appearance === "light")) {
+				const changed = appearance !== macOSReportedAppearance;
 				macOSReportedAppearance = appearance;
+				if (changed) {
+					// oxlint-disable-next-line unicorn/no-useless-spread -- listeners may unsubscribe while reporting
+					for (const listener of [...backgroundFallbackListeners]) {
+						try {
+							listener();
+						} catch (err) {
+							// Debug-level: a listener failure must not break sibling
+							// listeners or the appearance observer. Visible only in
+							// local debug logs, never in normal runs.
+							logger.debug("macOS appearance fallback listener failed", { err });
+						}
+					}
+				}
 				reevaluateAutoThemeForAppearance("macOS fallback");
 			}
 		});

package/src/tmux.ts

@@ -10,7 +10,13 @@ export function wrapTmuxPassthroughIfNeeded(payload: string, env: NodeJS.Process
 }
 
 const CLIENT_TERMTYPE_NAME = /^([A-Za-z][A-Za-z0-9._+-]*)(?=\s|\(|$)/u;
-const CLIENT_TERMINAL_TIMEOUT_MS = 500;
+// One `tmux display-message` round trip over the server socket, which answers in
+// single-digit milliseconds when healthy. 500ms kept losing the race on a loaded
+// machine (fork/exec of the tmux client alone can exceed it on a saturated box),
+// and a lost race is indistinguishable from "not tmux": the process then falls
+// back to the true-color profile for the whole session. 2s bounds the startup
+// stall only when tmux is genuinely wedged.
+const CLIENT_TERMINAL_TIMEOUT_MS = 2_000;
 /** Client `TERM` values that name their emulator; tmux records this on every version. */
 const CLIENT_TERMNAME_PROGRAMS: ReadonlyArray<readonly [RegExp, string]> = [
 	[/^xterm-kitty$/u, "kitty"],

package/src/tools/ast-edit.ts

@@ -1,3 +1,4 @@
+import { isRecord, sanitizeText } from "@oh-my-pi/pi-utils";
 import type { Component } from "../tui";
 import { Text } from "../components/text";
 import { replaceTabs } from "../utils";
@@ -14,7 +15,13 @@ import {
 } from "../render/render-utils";
 import { classifyGroupedLines, groupLineIndicesByBlank } from "./grouped-file-output";
 import type { OutputMeta } from "./output-meta";
-import type { NativeToolHead, NativeToolView, RenderResultOptions, ToolRenderer } from "./renderer";
+import type {
+	NativeToolHead,
+	NativeToolView,
+	RenderResultContextOptions,
+	RenderResultOptions,
+	ToolRenderer,
+} from "./renderer";
 import { code, compact, diff, node, span, text } from "../native/describe";
 import type { NativeChild, NativeNode } from "../native/node";
 import { diffStatsMeta, displayPath, errorText, fileDiffSection, noteText, resultText, statsText } from "./native-view";
@@ -190,7 +197,7 @@ export const astEditToolRenderer = {
 
 	renderResult(
 		result: { content: Array<{ type: string; text?: string }>; details?: AstEditToolDetails; isError?: boolean },
-		options: RenderResultOptions,
+		options: RenderResultContextOptions,
 		uiTheme: Theme,
 		args?: AstEditRenderArgs,
 	): Component {
@@ -245,6 +252,19 @@ export const astEditToolRenderer = {
 		// Resolve hyperlinks over the whole output so nested directory headers
 		// reconstruct across the blank-line groups the tree list collapses by.
 		const contexts = classifyGroupedLines(allLines, details?.cwd ?? details?.searchPath, details?.searchPath);
+		// The display lines are sanitized; reconstruct link targets from the original
+		// grouped headers only when they still align with those display lines.
+		const rawDetails = options.renderContext?.rawDetails;
+		const rawContent =
+			isRecord(rawDetails) && typeof rawDetails.displayContent === "string" ? rawDetails.displayContent : undefined;
+		const rawLines = rawContent?.split("\n");
+		const rawCwd = isRecord(rawDetails) && typeof rawDetails.cwd === "string" ? rawDetails.cwd : undefined;
+		const rawSearchPath =
+			isRecord(rawDetails) && typeof rawDetails.searchPath === "string" ? rawDetails.searchPath : undefined;
+		const rawContexts =
+			rawContent !== undefined && rawLines?.length === allLines.length && sanitizeText(rawContent) === textContent
+				? classifyGroupedLines(rawLines, rawCwd ?? rawSearchPath, rawSearchPath)
+				: undefined;
 		// Style lazily: collapsed bodies show only the first groups.
 		const styledLines: (string | undefined)[] = Array.from({ length: allLines.length }, () => undefined);
 		const styleLine = (index: number): string => {
@@ -255,12 +275,16 @@ export const astEditToolRenderer = {
 			// second vertical bar inside the frame border.
 			const display = replaceTabs(allLines[index]!.replace("│", " "));
 			let styled: string;
+			const linkPath =
+				ctx.headerPath && rawContexts?.[index]?.kind === ctx.kind && rawContexts[index]?.depth === ctx.depth
+					? (rawContexts[index]?.headerPath ?? ctx.headerPath)
+					: ctx.headerPath;
 			if (ctx.kind === "dir") {
 				const accent = uiTheme.fg("accent", display);
-				styled = ctx.headerPath ? fileHyperlink(ctx.headerPath, accent) : accent;
+				styled = linkPath ? fileHyperlink(linkPath, accent) : accent;
 			} else if (ctx.kind === "file") {
 				const tinted = uiTheme.fg(ctx.depth === 1 ? "accent" : "dim", display);
-				styled = ctx.headerPath ? fileHyperlink(ctx.headerPath, tinted) : tinted;
+				styled = linkPath ? fileHyperlink(linkPath, tinted) : tinted;
 			} else if (display.startsWith("+")) {
 				styled = uiTheme.fg("toolDiffAdded", display);
 			} else if (display.startsWith("-")) {