@linxiraos/pi-tui 1.2.1 → 1.3.0

package/src/terminal.ts

@@ -25,12 +25,13 @@ import {
 	NotifyProtocol,
 	setCellDimensions,
 	setOsc99Supported,
+	setTerminalBackgroundColor,
 	setTerminalGlyphProtocol,
 	TERMINAL,
 } from "./terminal-capabilities";
 import { tmuxMultiplexer } from "./multiplexers/tmux";
 import type { TerminalMultiplexerBackgroundColorCache } from "./multiplexers/types";
-import { terminalMultiplexerSessions } from "./terminal-multiplexer";
+import { classifyTerminalMultiplexerModule, terminalMultiplexerSessions } from "./terminal-multiplexer";
 import { setTmuxPaneApcTitles, tmuxSessionSpeaksTsp } from "./tmux";
 import { setHangulCompatibilityJamoWidth } from "./utils";
 import { translateWindowsAltGrSequence } from "./windows-altgr";
@@ -55,6 +56,38 @@ const TSP_OSC_PREFIX = `\x1b]877;${TSP_PREFIX.slice(2)}`;
 /** How long a TSP hello waits for its reply inside tmux, which answers DA1 itself. */
 const TSP_TMUX_HELLO_TIMEOUT_MS = 1000;
 
+/** Tern names itself in `TERM_PROGRAM`; a multiplexer started in a Tern pane may leave it behind. */
+function isTernPane(env: NodeJS.ProcessEnv): boolean {
+	return env.TERM_PROGRAM?.toLowerCase() === "tern";
+}
+
+/**
+ * Why a TSP `hello` cannot reach the terminal from this environment, or
+ * `null` when nothing in between is known to drop APC.
+ *
+ * In a Tern pane only a multiplexer's session marker counts: Tern sets
+ * `TERM=xterm-kitty`, so a `screen*`/`tmux*` TERM next to `TERM_PROGRAM=tern`
+ * without a marker was rewritten (shell rc, dev shell, `.env`), not set by a
+ * multiplexer. Elsewhere the TERM fallback keeps classifying sessions whose
+ * markers were stripped.
+ *
+ * devenv (2.0+) runs `devenv shell` in its own PTY and redraws the pane from a
+ * terminal emulator to keep its reload status line: it forwards DA1 to the
+ * real terminal but drops APC, so the DA1 reply always wins. It exports
+ * `DEVENV_RELOAD_FILE` only into that reloading shell; `devenv shell
+ * --no-reload` runs the shell on the real terminal.
+ */
+function tspPathBlocker(env: NodeJS.ProcessEnv): string | null {
+	const multiplexer = isTernPane(env)
+		? terminalMultiplexerSessions(env).find(session => session.ownsScreenGrid)
+		: classifyTerminalMultiplexerModule(env);
+	if (multiplexer?.ownsScreenGrid) return `inside a ${multiplexer.id} session, which swallows APC`;
+	if (env.DEVENV_RELOAD_FILE) {
+		return "inside devenv's reloading shell, which redraws the pane and drops APC; `devenv shell --no-reload` avoids it";
+	}
+	return null;
+}
+
 /**
  * The TSP message a reassembled input string holds, in APC form, or
  * `undefined` while its terminator has not arrived. An OSC 877 message may end
@@ -133,9 +166,22 @@ export function chunkForConPTY(data: string, maxChunkBytes: number = MAX_CONPTY_
 	let pos = 0;
 	while (pos < len) {
 		let bytes = 0;
-		// Index just past the most recent `\n` we've consumed inside [pos, i):
-		// the natural cut point that leaves escape sequences intact.
+		// Index just past the most recent line terminator we have consumed
+		// inside [pos, i): the natural cut point that leaves escape sequences
+		// and rows intact.
+		//
+		// Both terminators must be tracked. A full paint separates rows with
+		// `\r\n` and a newline alone is enough. A *diff* paint does not: TUI's
+		// row diff (`TUI#renderProviderFrame`, the `diffable` branch) addresses
+		// every changed row with `CSI row;1H` and closes it with a bare `\r`,
+		// emitting no `\n` anywhere in the frame. A newline-only tracker
+		// therefore finds no boundary in a diff paint and falls through to the
+		// hard cut at `i`, slicing the buffer through the middle of a row's
+		// text. Every boundary between two `process.stdout.write` calls is a
+		// point a foreign writer can inject into, so a hard cut lets unrelated
+		// output land inside a row instead of between rows.
 		let lastNewlineEnd = -1;
+		let lastCarriageReturnEnd = -1;
 		let i = pos;
 		while (i < len) {
 			const cu = data.charCodeAt(i);
@@ -161,16 +207,25 @@ export function chunkForConPTY(data: string, maxChunkBytes: number = MAX_CONPTY_
 				cuBytes = 3;
 			}
 			if (bytes + cuBytes > maxChunkBytes && i > pos) {
-				// Would overflow the cap. Cut at the last newline if we found one,
-				// otherwise hard-cut at the current code-point boundary.
-				const cut = lastNewlineEnd > pos ? lastNewlineEnd : i;
-				chunks.push(data.slice(pos, cut));
-				pos = cut;
+				// Cut at the last line terminator. A `\r` that opens a `\r\n` pair is
+				// never tracked (see below), so the pair always stays in one
+				// `WriteFile` call. Falls back to the code-point boundary `i` only
+				// when the window holds no terminator at all (a single row longer
+				// than the cap), which still makes forward progress.
+				const cut = Math.max(lastNewlineEnd, lastCarriageReturnEnd);
+				let end = cut > pos ? cut : i;
+				// A hard cut landing between `\r` and `\n` moves back before the `\r`.
+				if (end === i && data.charCodeAt(i) === 0x0a && data.charCodeAt(i - 1) === 0x0d && i - 1 > pos) end = i - 1;
+				chunks.push(data.slice(pos, end));
+				pos = end;
 				break;
 			}
 			bytes += cuBytes;
 			i += cuLen;
+			// A `\r` directly followed by `\n` is half of a `\r\n` pair, even when the
+			// `\n` lies past the cap, so it is never a cut point on its own.
 			if (cu === 0x0a) lastNewlineEnd = i;
+			else if (cu === 0x0d && data.charCodeAt(i) !== 0x0a) lastCarriageReturnEnd = i;
 		}
 		if (i >= len) {
 			chunks.push(data.slice(pos));
@@ -490,7 +545,7 @@ export type GlyphProtocolReportHandler = (supported: boolean) => void;
 /**
  * Outcome of the Tern Surface Protocol `hello` probe: the terminal's reply,
  * or null when it answered the DA1 sentinel first (no TSP) or the probe was
- * skipped (`PI_TUI_NATIVE=0`, multiplexers).
+ * skipped (`PI_TUI_NATIVE=0`, multiplexers, devenv's reloading shell).
  */
 export type TspHelloHandler = (hello: TspHello | null) => void;
 
@@ -590,6 +645,11 @@ export interface Terminal {
 	// so custom Terminals built against older pi-tui versions keep working.
 	readonly keyboardEnhancementExitSequence?: string | null;
 
+	// Re-asserts the main-screen enhanced keyboard mode after alternate-screen
+	// exit, or null when none is needed. Optional so custom Terminals built
+	// against older pi-tui versions keep working.
+	readonly keyboardEnhancementRestoreSequence?: string | null;
+
 	// Cursor positioning (relative to current position)
 	moveBy(lines: number): void; // Move cursor up (negative) or down (positive) by N lines
 
@@ -764,9 +824,11 @@ export interface ProcessTerminalOptions {
 	conpty?: boolean;
 	/**
 	 * Whether stdin is a native Windows console handle (win32, not WSL), whose
-	 * console host answers `CSI ? 9001 h` with win32-input-mode key records.
-	 * Defaults to `process.platform === "win32"`; only consulted when `conpty`
-	 * is also true.
+	 * console host is certain to answer `CSI ? 9001 h` with win32-input-mode key
+	 * records. When false (WSL), the keyboard fallback requests modifyOtherKeys
+	 * alongside win32-input-mode, since a WSL pty may not be relayed by a console
+	 * host. Defaults to `process.platform === "win32"`; only consulted when
+	 * `conpty` is also true.
 	 */
 	nativeWindowsConsole?: boolean;
 }
@@ -783,7 +845,8 @@ export class ProcessTerminal implements Terminal {
 	#isLoopStalled?: () => boolean;
 	#stdoutResizeListener?: () => void;
 	#kittyProtocolActive = false;
-	#kittyEnableSeq: string | null = null;
+	// Kitty flags omp pushed on its own stack frame; meaningful only while kitty is active.
+	#kittyFlags = 0;
 	#modifyOtherKeysActive = false;
 	#modifyOtherKeysTimeout?: Timer;
 	// Windows console fallback when kitty is unavailable: key records arrive as
@@ -878,6 +941,7 @@ export class ProcessTerminal implements Terminal {
 	#sixelSupportCallbacks: Array<(supported: boolean) => void> = [];
 	#tspPending = false;
 	#tspResult: TspHello | null | undefined;
+	#tspFallbackLogged = false;
 	#tspCallbacks: TspHelloHandler[] = [];
 	/** Hello deadline inside tmux, where no DA1 sentinel can end the probe. */
 	#tspTimeout: NodeJS.Timeout | undefined;
@@ -889,6 +953,12 @@ export class ProcessTerminal implements Terminal {
 	/** Resolved DECRQM support per private mode (mode → supported). */
 	#privateModeSupport = new Map<number, boolean>();
 	#privateModeCallbacks: PrivateModeReportHandler[] = [];
+	/**
+	 * Whether output and input reassert DEC 2004: set once DECRPM confirms it,
+	 * or at input attach inside a multiplexer that gates paste markers on the
+	 * pane's own mode without answering DECRQM (tmux <= 3.5a, #15596).
+	 */
+	#rearmBracketedPaste = false;
 	/** Whether DEC 2048 in-band resize notifications are currently enabled. */
 	#inBandResizeActive = false;
 	/** Reassembly buffer for a DEC 2048 in-band resize report split across stdin reads. */
@@ -913,14 +983,22 @@ export class ProcessTerminal implements Terminal {
 	}
 
 	get kittyEnableSequence(): string | null {
-		return this.#kittyProtocolActive ? this.#kittyEnableSeq : null;
+		return this.#kittyProtocolActive ? `\x1b[>${this.#kittyFlags}u` : null;
 	}
 
 	get keyboardEnhancementEnterSequence(): string | null {
-		if (this.#kittyProtocolActive) return this.#kittyEnableSeq;
+		if (this.#kittyProtocolActive) return `\x1b[>${this.#kittyFlags}u`;
 		return this.#modifyOtherKeysActive ? "\x1b[>4;2m" : null;
 	}
 
+	get keyboardEnhancementRestoreSequence(): string | null {
+		// `CSI = flags ; 1 u` replaces the main-screen stack top, which is omp's own
+		// frame, so it is a no-op wherever per-screen stacks work. Windows Terminal
+		// 1.25–1.27 restore the pre-push flags on `?1049l` (microsoft/terminal#20763),
+		// dropping to legacy keys: Shift+Enter arrives as `\r`, Ctrl+Enter as `\n`.
+		return this.#kittyProtocolActive ? `\x1b[=${this.#kittyFlags};1u` : null;
+	}
+
 	get keyboardEnhancementExitSequence(): string | null {
 		// kitty is a stack push (per-screen), so the matching pop balances alt-screen
 		// entry. xterm modifyOtherKeys is a single global flag with no per-screen
@@ -1014,13 +1092,13 @@ export class ProcessTerminal implements Terminal {
 	}
 
 	get tspExpected(): boolean {
-		// A multiplexer started from Tern can leave `TERM_PROGRAM=tern` behind
-		// while swallowing APC, even when `PI_TUI_NATIVE=1` forces the probe.
+		// A multiplexer or relay started from Tern can leave `TERM_PROGRAM=tern`
+		// behind while swallowing APC, even when `PI_TUI_NATIVE=1` forces the probe.
 		return (
-			$env.TERM_PROGRAM?.toLowerCase() === "tern" &&
-			!isInsideTerminalMultiplexer($env) &&
+			isTernPane($env) &&
+			tspPathBlocker($env) === null &&
 			!isTerminalHeadless() &&
-			this.#shouldQueryTspSupport()
+			this.#tspProbeSkipReason() === null
 		);
 	}
 
@@ -1048,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.
@@ -1128,6 +1208,9 @@ export class ProcessTerminal implements Terminal {
 
 		// Enable bracketed paste mode - terminal will wrap pastes in \x1b[200~ ... \x1b[201~
 		this.#safeWrite("\x1b[?2004h");
+		this.#rearmBracketedPaste =
+			terminalMultiplexerSessions($env).some(multiplexer => multiplexer.gatesBracketedPaste) ||
+			classifyTerminalMultiplexerModule($env)?.gatesBracketedPaste === true;
 
 		// Force normal cursor-key (DECCKM) and numeric-keypad mode (terminfo
 		// `rmkx` = "\x1b[?1l\x1b>"). zeta decodes both CSI ("\x1b[A") and SS3
@@ -1501,7 +1584,10 @@ export class ProcessTerminal implements Terminal {
 					}
 					case "tsp": {
 						// DA1 before any `tsp;r` reply: the terminal doesn't speak TSP.
-						this.#resolveTspSupport(null);
+						this.#resolveTspSupport(
+							null,
+							"DA1 was answered before a hello reply: the terminal, or a layer in between, dropped the APC query",
+						);
 						break;
 					}
 				}
@@ -1536,19 +1622,17 @@ export class ProcessTerminal implements Terminal {
 					// ConPTY (native Windows and WSL) drops Shift+letter keypresses
 					// entirely when flag 4 (report alternate keys) is set. Use flag 1
 					// (disambiguate only), preserving flag 2 if already active.
-					this.#kittyEnableSeq = (reportedFlags & 2) !== 0 ? "\x1b[>3u" : "\x1b[>1u";
-					this.#safeWrite(this.#kittyEnableSeq);
+					this.#kittyFlags = (reportedFlags & 2) !== 0 ? 3 : 1;
 				} else if ((reportedFlags & 2) !== 0) {
 					// Preserve event-type reporting already enabled by a parent app.
 					// Push level-2 to keep its shortcuts reporting consistently.
-					this.#kittyEnableSeq = "\x1b[>7u";
-					this.#safeWrite(this.#kittyEnableSeq);
+					this.#kittyFlags = 7;
 				} else {
 					// Disambiguate escape codes and report base-layout keys for physical
 					// shortcut matching, without event reporting that caused regression #3259.
-					this.#kittyEnableSeq = "\x1b[>5u";
-					this.#safeWrite(this.#kittyEnableSeq);
+					this.#kittyFlags = 5;
 				}
+				this.#safeWrite(`\x1b[>${this.#kittyFlags}u`);
 				return;
 			}
 
@@ -1673,8 +1757,11 @@ export class ProcessTerminal implements Terminal {
 
 		// Handler that pipes stdin data through the buffer
 		this.#stdinDataHandler = (data: string) => {
-			// Recover modes reset by the host before the user's next paste.
-			if (data && this.#active && this.#privateModeSupport.get(2004)) this.#safeWrite("\x1b[?2004h");
+			// Recover modes reset by the host before the user's next paste. Not
+			// mid-paste: the host is plainly in 2004 then, and per-key reads would
+			// turn one paste into thousands of writes (#15757).
+			if (data && this.#active && this.#rearmBracketedPaste && !this.#stdinBuffer!.pasting)
+				this.#safeWrite("\x1b[?2004h");
 			if (this.#win32PasteNormalizer) this.#win32PasteNormalizer.process(data);
 			else this.#stdinBuffer!.process(data);
 		};
@@ -1837,16 +1924,27 @@ export class ProcessTerminal implements Terminal {
 		}
 	}
 
-	#shouldQueryTspSupport(): boolean {
+	/** Why the `hello` probe does not run, or `null` when it does. */
+	#tspProbeSkipReason(): string | null {
 		const override = $env.PI_TUI_NATIVE;
-		if (override === "0") return false;
+		if (override === "0") return "PI_TUI_NATIVE=0";
 		// tmux makes APC bodies the pane title unless the hosting terminal asked
 		// for TSP through `@tern-tsp`: no override may force the probe there.
-		if (tmuxMultiplexer.isInside($env)) return tmuxSessionSpeaksTsp($env);
-		if (override === "1") return true;
-		// Multiplexers swallow APC, so the reply could never arrive.
-		if (isInsideTerminalMultiplexer($env)) return false;
-		return !isBunTestRuntime();
+		if (tmuxMultiplexer.isInside($env)) {
+			return tmuxSessionSpeaksTsp($env) ? null : "inside a tmux session without the @tern-tsp option";
+		}
+		if (override === "1") return null;
+		// The reply could never arrive.
+		const blocker = tspPathBlocker($env);
+		if (blocker !== null) return blocker;
+		return isBunTestRuntime() && $env.PI_TUI_TSP_PROBE !== "1" ? "bun test runtime" : null;
+	}
+
+	/** A Tern pane that ends up on the classic renderer says why in the log, once. */
+	#logTspFallback(reason: string): void {
+		if (this.#tspFallbackLogged || !isTernPane($env)) return;
+		this.#tspFallbackLogged = true;
+		logger.debug("TSP: Tern pane keeps the classic renderer", { reason });
 	}
 
 	#queryTspSupport(): void {
@@ -1854,7 +1952,9 @@ export class ProcessTerminal implements Terminal {
 		this.#tspResult = undefined;
 		this.#tspReplyBuffer = "";
 		if (this.#dead) return;
-		if (!this.#shouldQueryTspSupport()) {
+		const skipReason = this.#tspProbeSkipReason();
+		if (skipReason !== null) {
+			this.#logTspFallback(skipReason);
 			this.#tspResult = null;
 			for (const cb of this.#tspCallbacks) cb(null);
 			return;
@@ -1866,7 +1966,7 @@ export class ProcessTerminal implements Terminal {
 			setTmuxPaneApcTitles(false, $env);
 			this.#tspTimeout = setTimeout(() => {
 				this.#tspTimeout = undefined;
-				this.#resolveTspSupport(null);
+				this.#resolveTspSupport(null, `no hello reply through tmux within ${TSP_TMUX_HELLO_TIMEOUT_MS} ms`);
 			}, TSP_TMUX_HELLO_TIMEOUT_MS);
 			this.#safeWrite(encodeTspHelloQuery());
 			return;
@@ -1894,12 +1994,14 @@ export class ProcessTerminal implements Terminal {
 		this.#inputHandler?.(sequence);
 	}
 
-	#resolveTspSupport(hello: TspHello | null): void {
+	/** `reason` says why a `null` hello means no TSP. */
+	#resolveTspSupport(hello: TspHello | null, reason?: string): void {
 		if (!this.#tspPending) return;
 		this.#tspPending = false;
 		const result = hello !== null && hello.v === TSP_VERSION ? hello : null;
 		if (hello !== null && result === null) logger.warn("TSP: unsupported protocol version", { v: hello.v });
 		if (result === null) {
+			this.#logTspFallback(reason ?? `unsupported protocol version ${String(hello?.v)}`);
 			this.#endTspTmuxPane();
 		} else {
 			clearTimeout(this.#tspTimeout);
@@ -1942,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;
@@ -1967,10 +2073,11 @@ export class ProcessTerminal implements Terminal {
 	#enableModifyOtherKeysFallback(): void {
 		if (this.#kittyProtocolActive || this.#modifyOtherKeysActive || this.#win32InputDecoder) return;
 		const ssh = isSshSession();
-		if (this.#conpty && this.#nativeWindowsConsole && !ssh) {
+		if (this.#conpty && !ssh) {
 			// The Windows console host ignores modifyOtherKeys and folds Shift+Enter
-			// into a bare CR. win32-input-mode is answered by the console host
-			// serving this process, so it works under every local ConPTY terminal.
+			// into a bare CR (Ctrl+Enter into LF). win32-input-mode is answered by the
+			// console host serving this process, so it works under every local ConPTY
+			// terminal, and under WSL through the `wsl.exe` relay's console host too.
 			// Under sshd the console host is fed the remote terminal's VT stream,
 			// and the mode splits arrow keys into Escape plus literal text (#14034).
 			this.#safeWrite("\x1b[?9001h");
@@ -1981,7 +2088,10 @@ export class ProcessTerminal implements Terminal {
 				data => this.#stdinBuffer?.process(data),
 				() => this.#releaseWin32PendingSequence(),
 			);
-			return;
+			// A WSL pty is not always relayed by a console host (tmux, VS Code
+			// Remote-WSL, WSLg terminals). Those ignore 9001 and keep sending plain
+			// VT, which the decoder passes through, so also ask for modifyOtherKeys.
+			if (this.#nativeWindowsConsole) return;
 		}
 		// A remote terminal with no identifying env may not understand the request.
 		if (ssh && (TERMINAL.id === "base" || TERMINAL.id === "trueColor")) return;
@@ -2075,6 +2185,7 @@ export class ProcessTerminal implements Terminal {
 		// only true here after an explicit DECRPM reply (the DA1-sentinel
 		// fallback resolves unsupported).
 		if (mode === 2004 && supported) {
+			this.#rearmBracketedPaste = true;
 			this.#stdinBuffer?.setRawPasteStallProbe(this.#isLoopStalled);
 		}
 	}
@@ -2209,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
@@ -2302,6 +2415,7 @@ export class ProcessTerminal implements Terminal {
 		this.#da1SentinelOwners.length = 0;
 		this.#privateModeCallbacks = [];
 		this.#privateModeSupport.clear();
+		this.#rearmBracketedPaste = false;
 		this.#xtermScrollToBottomRestoreModes.clear();
 		this.#reportedColumns = undefined;
 		this.#reportedRows = undefined;
@@ -2413,7 +2527,7 @@ export class ProcessTerminal implements Terminal {
 	write(data: string): void {
 		// Hosts can reset bracketed paste (e.g. iTerm2's Terminal State toggle).
 		// Reassert it with existing output, never on a timer while idle.
-		if (data && this.#active && this.#privateModeSupport.get(2004)) data = `\x1b[?2004h${data}`;
+		if (data && this.#active && this.#rearmBracketedPaste) data = `\x1b[?2004h${data}`;
 		this.#safeWrite(data);
 		if (this.#writeLogPath) {
 			try {

package/src/theme/symbols.d.ts

@@ -9,7 +9,7 @@ export type SymbolMap = Record<SymbolKey, string>;
  * resolves through `Theme.cmd` to either a dedicated `cmd.*` symbol or an
  * existing `icon.*` symbol shared with the rest of the UI.
  */
-export type SlashCommandIconName = "action" | "prompt" | "extension" | "settings" | "gear" | "shield" | "wave" | "compass" | "inbox" | "swap" | "expand" | "computer" | "eye" | "todo" | "stats" | "news" | "keyboard" | "export" | "clipboard" | "share" | "broadcast" | "globe" | "copy" | "plus" | "restart" | "eraser" | "trash" | "compress" | "vibrate" | "handoff" | "history" | "question" | "rocket" | "stethoscope" | "redo" | "bug" | "memory" | "pencil" | "folderMove" | "folderPlus" | "folderMinus" | "hammer" | "power" | "cart" | "model" | "plan" | "prewalk" | "goal" | "pause" | "loop" | "session" | "jobs" | "gauge" | "context" | "agents" | "branch" | "tree" | "signIn" | "signOut" | "advisor" | "host" | "package" | "fast" | "voice" | "tools" | "rule" | "skill" | "mcp" | "pin";
+export type SlashCommandIconName = "action" | "prompt" | "extension" | "settings" | "gear" | "shield" | "wave" | "compass" | "inbox" | "swap" | "expand" | "computer" | "eye" | "todo" | "stats" | "news" | "keyboard" | "export" | "clipboard" | "share" | "broadcast" | "globe" | "copy" | "plus" | "restart" | "eraser" | "trash" | "compress" | "vibrate" | "handoff" | "history" | "question" | "rocket" | "stethoscope" | "redo" | "bug" | "memory" | "pencil" | "folderMove" | "folderPlus" | "folderMinus" | "hammer" | "power" | "cart" | "model" | "plan" | "prewalk" | "goal" | "pause" | "loop" | "session" | "jobs" | "gauge" | "context" | "ghost" | "agents" | "branch" | "tree" | "signIn" | "signOut" | "advisor" | "host" | "package" | "fast" | "voice" | "tools" | "rule" | "skill" | "mcp" | "pin";
 export declare const SYMBOL_PRESETS: Record<SymbolPreset, SymbolMap>;
 export type SpinnerType = "status" | "activity";
 export declare const SPINNER_FRAMES: Record<SymbolPreset, Record<SpinnerType, string[]>>;

package/src/theme/symbols.ts

@@ -371,6 +371,7 @@ export type SlashCommandIconName =
 	| "jobs"
 	| "gauge"
 	| "context"
+	| "ghost"
 	| "agents"
 	| "branch"
 	| "tree"

package/src/theme/theme-class.ts

@@ -729,6 +729,7 @@ export class Theme {
 			jobs: this.#symbols["icon.job"],
 			gauge: this.#symbols["icon.throughput"],
 			context: this.#symbols["icon.context"],
+			ghost: this.#symbols["icon.ghost"],
 			agents: this.#symbols["icon.agents"],
 			branch: this.#symbols["icon.branch"],
 			tree: this.#symbols["icon.worktree"],

package/src/theme/theme.d.ts

@@ -7,6 +7,17 @@ export { isValidThemeColor, type ThemeBg, type ThemeColor } from "./schema";
 export { getAvailableSymbolPresets, isValidSymbolPreset, type SpinnerType, type SymbolKey, type SymbolPreset, } from "./symbols";
 export { Theme } from "./theme-class";
 export { createHighlightStream, getEditorTheme, getMarkdownTheme, getMarkdownThemeWithLinkTargets, getSelectListTheme, getSettingsListTheme, getSymbolTheme, highlightCode, setMarkdownMermaidRendering, warmHighlighter, } from "./tui-adapters";
+/**
+ * Subscribe to native fallback appearance changes independently of theme changes.
+ * Consumers must re-check the effective background: COLORFGBG can override it.
+ */
+export declare function onTerminalBackgroundFallbackChange(callback: () => void): () => void;
+/**
+ * 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 declare function detectTerminalBackground(): "dark" | "light";
 /** Active theme; imports remain live across initialization, previews, and theme switches. */
 export declare var theme: Theme;
 type ThemeBinding = (value: Theme) => void;

package/src/theme/theme.ts

@@ -5,7 +5,7 @@ import type { Terminal, TerminalAppearance } from "../terminal";
 import { colorLuma } from "@linxiraos/pi-utils/color";
 import { getCustomThemesDir } from "@linxiraos/pi-utils/dirs";
 import * as logger from "@linxiraos/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/thinking.d.ts

@@ -37,6 +37,11 @@ export declare function shouldDisableReasoning(level: ThinkingLevel | undefined)
  * Resolves a selector against the current model while preserving explicit "off".
  */
 export declare function resolveThinkingLevelForModel(model: Model | undefined, level: ThinkingLevel | undefined): ResolvedThinkingLevel | undefined;
+/**
+ * Level applied to `model` when the user has not picked one for it (carried,
+ * global default, auto). Unverified thinking stays unset until the user picks.
+ */
+export declare function automaticThinkingLevel<T>(model: Model | undefined, fallback: T): T | undefined;
 /**
  * Sentinel selector for the coding-agent "auto" thinking mode. Kept entirely
  * inside the coding-agent layer: it is never an {@link Effort} or

package/src/thinking.ts

@@ -132,6 +132,14 @@ export function resolveThinkingLevelForModel(
 	return clampThinkingLevelForModel(model, level);
 }
 
+/**
+ * Level applied to `model` when the user has not picked one for it (carried,
+ * global default, auto). Unverified thinking stays unset until the user picks.
+ */
+export function automaticThinkingLevel<T>(model: Model | undefined, fallback: T): T | undefined {
+	return model?.thinking?.unverified ? undefined : fallback;
+}
+
 /**
  * Sentinel selector for the coding-agent "auto" thinking mode. Kept entirely
  * inside the coding-agent layer: it is never an {@link Effort} or
@@ -374,7 +382,7 @@ export function modelSupportsEffortCeiling(model: Model, ceiling: Effort): boole
  * models.
  */
 export function resolveProvisionalAutoLevel(model: Model | undefined): Effort | undefined {
-	if (!model?.reasoning) return undefined;
+	if (!model?.reasoning || model.thinking?.unverified) return undefined;
 	const preferred = model.thinking?.defaultLevel ?? Effort.High;
 	return clampAutoThinkingEffort(model, preferred === Effort.Max ? Effort.XHigh : preferred, Effort.XHigh);
 }