@linxiraos/pi-tui 1.1.27 → 1.2.0

package/src/terminal-multiplexer.ts

@@ -1,45 +1,124 @@
-/** True when this process is running inside a Herdr pane. */
-export function isInsideHerdr(env: NodeJS.ProcessEnv = Bun.env): boolean {
-	// HERDR_ENV=1 is canonical. Identity vars survive env-sanitizing launchers
-	// that drop HERDR_ENV. Do not use HERDR_SOCKET_PATH, HERDR_BIN_PATH,
-	// HERDR_SESSION, HERDR_CONFIG_PATH, or HERDR_CLIENT_SOCKET_PATH here: they
-	// are client-side and can be set outside a Herdr pane, matching the
-	// CMUX_SOCKET_PATH warning below.
-	if (env.HERDR_ENV === "1") return true;
-	if (env.HERDR_PANE_ID || env.HERDR_TAB_ID || env.HERDR_WORKSPACE_ID) return true;
-	return false;
+import { cmuxMultiplexer } from "./multiplexers/cmux";
+import { herdrMultiplexer } from "./multiplexers/herdr";
+import { orcaMultiplexer } from "./multiplexers/orca";
+import { screenMultiplexer } from "./multiplexers/screen";
+import { tmuxMultiplexer } from "./multiplexers/tmux";
+import type { TerminalMultiplexerModule, TerminalMultiplexerNotificationRequest } from "./multiplexers/types";
+import { wmuxMultiplexer } from "./multiplexers/wmux";
+import { zellijMultiplexer } from "./multiplexers/zellij";
+
+/**
+ * Every multiplexer omp recognizes, in classification order within each
+ * precedence tier. Adding a multiplexer means adding its module here.
+ */
+const registry = [
+	herdrMultiplexer,
+	tmuxMultiplexer,
+	screenMultiplexer,
+	zellijMultiplexer,
+	cmuxMultiplexer,
+	wmuxMultiplexer,
+	orcaMultiplexer,
+] as const satisfies readonly TerminalMultiplexerModule[];
+
+/** Terminal multiplexers omp recognizes. */
+export type TerminalMultiplexer = (typeof registry)[number]["id"];
+
+const TERMINAL_MULTIPLEXERS: readonly TerminalMultiplexerModule<TerminalMultiplexer>[] = registry;
+const MULTIPLEXERS_BY_ID = Object.fromEntries(
+	TERMINAL_MULTIPLEXERS.map(multiplexer => [multiplexer.id, multiplexer]),
+) as Record<TerminalMultiplexer, TerminalMultiplexerModule<TerminalMultiplexer>>;
+const SESSION_TIER = TERMINAL_MULTIPLEXERS.filter(multiplexer => multiplexer.precedence === "session");
+const OUTER_APP_TIER = TERMINAL_MULTIPLEXERS.filter(multiplexer => multiplexer.precedence === "outerApp");
+const NOTIFICATION_TIER_ORDER = ["pane", "surface", "inBand"] as const;
+// Innermost target first: a pane inside a surface must receive its own signal
+// before the containing surface, followed by in-band rewrites. Registry order
+// breaks ties within a tier (sort is stable).
+const NOTIFIERS = TERMINAL_MULTIPLEXERS.flatMap(multiplexer =>
+	multiplexer.notifier ? [{ multiplexer, notifier: multiplexer.notifier }] : [],
+).sort((a, b) => NOTIFICATION_TIER_ORDER.indexOf(a.notifier.tier) - NOTIFICATION_TIER_ORDER.indexOf(b.notifier.tier));
+
+/** Every environment variable multiplexer classification reads, including the TERM fallback. */
+export const TERMINAL_MULTIPLEXER_ENV_KEYS: readonly string[] = [
+	...TERMINAL_MULTIPLEXERS.flatMap(multiplexer => multiplexer.sessionEnvKeys),
+	"TERM",
+];
+
+/**
+ * Whether an explicit session marker identifies the current provider.
+ *
+ * TERM is intentionally excluded: it is a classification fallback, not proof
+ * that a particular multiplexer session owns the current grid.
+ */
+export function hasTerminalMultiplexerSession(
+	multiplexer: TerminalMultiplexer,
+	env: NodeJS.ProcessEnv = Bun.env,
+): boolean {
+	return MULTIPLEXERS_BY_ID[multiplexer].isInside(env);
 }
 
-/** Terminal multiplexers zeta recognizes as owning the screen grid. */
-export type TerminalMultiplexer = "herdr" | "tmux" | "screen" | "zellij" | "cmux" | "wmux";
+/**
+ * Every multiplexer whose explicit session markers are present, in registry
+ * order. Nested sessions all appear; TERM is not consulted.
+ */
+export function terminalMultiplexerSessions(
+	env: NodeJS.ProcessEnv = Bun.env,
+): TerminalMultiplexerModule<TerminalMultiplexer>[] {
+	return TERMINAL_MULTIPLEXERS.filter(multiplexer => multiplexer.isInside(env));
+}
 
 /**
- * Classify which terminal multiplexer owns the current screen grid, or `null`
- * for a direct terminal. Single source of truth for both the render-path gate
+ * The multiplexer TERM names, whether or not its session markers survived.
+ * This is classification's TERM fallback; session markers are not consulted.
+ */
+export function terminalMultiplexerForTerm(
+	env: NodeJS.ProcessEnv = Bun.env,
+): TerminalMultiplexerModule<TerminalMultiplexer> | undefined {
+	const term = env.TERM?.toLowerCase() ?? "";
+	return TERMINAL_MULTIPLEXERS.find(
+		multiplexer => multiplexer.termPrefix !== undefined && term.startsWith(multiplexer.termPrefix),
+	);
+}
+
+/**
+ * Registry entry for the multiplexer hosting the current process, or
+ * `undefined` for a direct terminal. Same precedence as
+ * {@link classifyTerminalMultiplexer}.
+ */
+export function classifyTerminalMultiplexerModule(
+	env: NodeJS.ProcessEnv = Bun.env,
+): TerminalMultiplexerModule<TerminalMultiplexer> | undefined {
+	return (
+		SESSION_TIER.find(multiplexer => multiplexer.isInside(env)) ??
+		terminalMultiplexerForTerm(env) ??
+		OUTER_APP_TIER.find(multiplexer => multiplexer.isInside(env))
+	);
+}
+
+/**
+ * Classify which terminal multiplexer hosts the current process, or `null` for
+ * a direct terminal. Single source of truth for both the render-path gate
  * (`isInsideTerminalMultiplexer`) and the debug snapshot label.
  *
- * TMUX/STY/ZELLIJ, Herdr, and the CMUX/WMUX workspace/surface/remote-transport
- * markers are authoritative session signals. TERM can also survive when those
- * are stripped (`sudo` without -E, `su`, env-sanitizing launchers/ssh). Do not
- * use CMUX_SOCKET_PATH / WMUX_CLI / WMUX_PIPE here: they are CLI socket/path
- * overrides and can be set outside a CMUX/WMUX terminal. wmux is a Windows
- * multiplexer (Electron + xterm.js) modeled on cmux/herdr that repaints its
- * pane in place and exports WMUX=1 plus a native WMUX_SURFACE_ID.
+ * Session markers are authoritative. TERM can also survive when those markers
+ * are stripped (`sudo` without -E, `su`, env-sanitizing launchers/ssh), so a
+ * `tmux`/`screen` TERM prefix comes next. Outer applications such as Orca rank
+ * last so a multiplexer running inside them wins.
  */
 export function classifyTerminalMultiplexer(env: NodeJS.ProcessEnv = Bun.env): TerminalMultiplexer | null {
-	if (isInsideHerdr(env)) return "herdr";
-	if (env.TMUX) return "tmux";
-	if (env.STY) return "screen";
-	if (env.ZELLIJ) return "zellij";
-	if (env.CMUX_WORKSPACE_ID || env.CMUX_SURFACE_ID || env.CMUX_REMOTE_TRANSPORT) return "cmux";
-	if (env.WMUX === "1" || env.WMUX_SURFACE_ID) return "wmux";
-	const term = env.TERM?.toLowerCase() ?? "";
-	if (term.startsWith("tmux")) return "tmux";
-	if (term.startsWith("screen")) return "screen";
-	return null;
+	return classifyTerminalMultiplexerModule(env)?.id ?? null;
 }
 
-/** True when a terminal multiplexer owns the current screen grid. */
+/** True when the classified multiplexer owns the current screen grid. */
 export function isInsideTerminalMultiplexer(env: NodeJS.ProcessEnv = Bun.env): boolean {
-	return classifyTerminalMultiplexer(env) !== null;
+	return classifyTerminalMultiplexerModule(env)?.ownsScreenGrid ?? false;
+}
+
+/**
+ * Offer a notification to every active session's notifier, innermost tier
+ * first. Returns whether one delivered it; otherwise the terminal fallback
+ * applies unchanged.
+ */
+export function routeTerminalMultiplexerNotification(request: TerminalMultiplexerNotificationRequest): boolean {
+	return NOTIFIERS.some(({ multiplexer, notifier }) => multiplexer.isInside(request.env) && notifier.send(request));
 }

package/src/terminal.d.ts

@@ -128,13 +128,21 @@ export type TspHelloHandler = (hello: TspHello | null) => void;
 export type CursorShape = "default" | "block" | "underline" | "bar";
 export declare const CURSOR_SHAPE_CODES: Record<CursorShape, number>;
 export interface Terminal {
+    /**
+     * Start the terminal with input, resize, and host-disconnect handlers.
+     * Unless input is deferred, this sends capability probes; a terminal that
+     * cannot parse one may leave concealed bytes on the cursor row, so the
+     * caller repaints after starting.
+     */
     start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => void, options?: TerminalStartOptions): void;
     /**
      * Take ownership of stdin after a `deferInput` start: enable raw mode,
      * attach input handlers, and run the capability probes start() skipped.
      * Bytes the user typed in cooked mode meanwhile are replayed through
-     * `onInput`. No-op when input was never deferred. Optional so custom
-     * Terminals built against older pi-tui versions keep working.
+     * `onInput`. No-op when input was never deferred. Like {@link start}, the
+     * probes may leave concealed bytes on the cursor row, so the caller
+     * repaints afterwards. Optional so custom Terminals built against older
+     * pi-tui versions keep working.
      */
     enableInput?(): void;
     stop(): void;
@@ -222,6 +230,12 @@ export interface Terminal {
      * `status` is the DECRPM value when the terminal answered DECRQM.
      */
     onPrivateModeReport?(callback: PrivateModeReportHandler): void;
+    /**
+     * Report whether DA1 advertises SIXEL (attribute 4), replaying the latest
+     * advertisement to late subscribers. A missing attribute does not rule out
+     * support discovered through another graphics query.
+     */
+    onSixelSupport?(callback: (supported: boolean) => void): void;
     /**
      * Register a callback fired once the startup Glyph Protocol handshake
      * resolves (see {@link GlyphProtocolReportHandler}). A subscriber that
@@ -290,10 +304,11 @@ export declare class ProcessTerminal implements Terminal {
     onAppearanceReport(callback: (appearance: TerminalAppearance, requestToken?: TerminalAppearanceRequestToken) => void): () => void;
     /**
      * Re-query the terminal background through the startup DA1-sentinel FIFO,
-     * pending/queued gating, parsing, dedup, and appearance callbacks. Inside
-     * tmux, only this explicit path first passes an OSC 11 query to the outer
-     * terminal, waits briefly for tmux to consume the response into its cache,
-     * then reads that cache with a direct query. The outer query deliberately has
+     * pending/queued gating, parsing, dedup, and appearance callbacks. Inside a
+     * multiplexer that answers OSC 11 from a cache (tmux), only this explicit
+     * path first passes an OSC 11 query to the outer terminal, waits briefly for
+     * the multiplexer to consume the response into its cache, then reads that
+     * cache with a direct query. The outer query deliberately has
      * no DA1 sentinel: multiplexers can decode a fragmented DA1 response as a key
      * sequence and leak the remaining bytes into the editor. Startup and Mode 2031
      * probes remain direct. Suppressed while inactive, headless, or after teardown.
@@ -301,6 +316,7 @@ export declare class ProcessTerminal implements Terminal {
     refreshAppearance(requestToken?: TerminalAppearanceRequestToken): TerminalAppearanceRequestToken | void;
     onPrivateModeReport(callback: PrivateModeReportHandler): void;
     onGlyphProtocolReport(callback: GlyphProtocolReportHandler): void;
+    onSixelSupport(callback: (supported: boolean) => void): void;
     onTspHello(callback: TspHelloHandler): void;
     get tspProbePending(): boolean;
     get tspExpected(): boolean;

package/src/terminal.ts

@@ -3,6 +3,7 @@ import * as fs from "node:fs";
 import { TtyWriter } from "@linxiraos/pi-natives";
 import { $env, isBunTestRuntime, isTerminalHeadless, isWsl } from "@linxiraos/pi-utils/env";
 import * as logger from "@linxiraos/pi-utils/logger";
+import { popLoopPhase, pushLoopPhase } from "@linxiraos/pi-utils/loop-phase";
 import * as postmortem from "@linxiraos/pi-utils/postmortem";
 import { restoreTerminalStderr, suppressTerminalStderr } from "@linxiraos/pi-utils/stderr-guard";
 import { TSP_VERSION } from "@linxiraos/pi-wire";
@@ -27,7 +28,10 @@ import {
 	setTerminalGlyphProtocol,
 	TERMINAL,
 } from "./terminal-capabilities";
-import { isInsideTmux, wrapTmuxPassthrough } from "./tmux";
+import { tmuxMultiplexer } from "./multiplexers/tmux";
+import type { TerminalMultiplexerBackgroundColorCache } from "./multiplexers/types";
+import { terminalMultiplexerSessions } from "./terminal-multiplexer";
+import { setTmuxPaneApcTitles, tmuxSessionSpeaksTsp } from "./tmux";
 import { setHangulCompatibilityJamoWidth } from "./utils";
 import { translateWindowsAltGrSequence } from "./windows-altgr";
 import { Win32InputModeDecoder, Win32PasteMarkerNormalizer } from "./windows-input-mode";
@@ -48,6 +52,9 @@ const WIN32_RELAYED_ESCAPE_TIMEOUT_MS = 75;
  */
 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;
+
 /**
  * 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
@@ -501,7 +508,12 @@ export const CURSOR_SHAPE_CODES: Record<CursorShape, number> = {
 	bar: 6,
 };
 export interface Terminal {
-	// Start the terminal with input, resize, and host-disconnect handlers.
+	/**
+	 * Start the terminal with input, resize, and host-disconnect handlers.
+	 * Unless input is deferred, this sends capability probes; a terminal that
+	 * cannot parse one may leave concealed bytes on the cursor row, so the
+	 * caller repaints after starting.
+	 */
 	start(
 		onInput: (data: string) => void,
 		onResize: () => void,
@@ -513,8 +525,10 @@ export interface Terminal {
 	 * Take ownership of stdin after a `deferInput` start: enable raw mode,
 	 * attach input handlers, and run the capability probes start() skipped.
 	 * Bytes the user typed in cooked mode meanwhile are replayed through
-	 * `onInput`. No-op when input was never deferred. Optional so custom
-	 * Terminals built against older pi-tui versions keep working.
+	 * `onInput`. No-op when input was never deferred. Like {@link start}, the
+	 * probes may leave concealed bytes on the cursor row, so the caller
+	 * repaints afterwards. Optional so custom Terminals built against older
+	 * pi-tui versions keep working.
 	 */
 	enableInput?(): void;
 
@@ -646,6 +660,12 @@ export interface Terminal {
 	 * `status` is the DECRPM value when the terminal answered DECRQM.
 	 */
 	onPrivateModeReport?(callback: PrivateModeReportHandler): void;
+	/**
+	 * Report whether DA1 advertises SIXEL (attribute 4), replaying the latest
+	 * advertisement to late subscribers. A missing attribute does not rule out
+	 * support discovered through another graphics query.
+	 */
+	onSixelSupport?(callback: (supported: boolean) => void): void;
 	/**
 	 * Register a callback fired once the startup Glyph Protocol handshake
 	 * resolves (see {@link GlyphProtocolReportHandler}). A subscriber that
@@ -707,9 +727,18 @@ function parseOsc99KeyValues(section: string): Map<string, string> {
 	}
 	return values;
 }
+/**
+ * Brackets the startup capability probes. A terminal that cannot parse a probe
+ * prints it as text at the cursor (Apple Terminal drops `ESC _`/`ESC \` and
+ * prints APC payloads, and abandons DECRQM at its `$`, printing the final `p`).
+ * DECSC, autowrap off, and SGR 8 (conceal) keep that text invisible and on the
+ * cursor row, so it can neither wrap nor scroll the screen; DECRC puts the
+ * cursor back. The screen owner repaints the row afterwards (see
+ * {@link Terminal.start} / {@link Terminal.enableInput}).
+ */
+const PROBE_GUARD_BEGIN = "\x1b7\x1b[?7l\x1b[8m";
+const PROBE_GUARD_END = "\x1b[28m\x1b[?7h\x1b8";
 const XTERM_SCROLL_TO_BOTTOM_MODES = [1010, 1011] as const;
-type Osc11QueryRoute = "direct" | "tmux";
-const TMUX_OSC11_CACHE_REFRESH_DELAY_MS = 100;
 
 function isXtermScrollToBottomMode(mode: number): boolean {
 	return mode === 1010 || mode === 1011;
@@ -830,10 +859,10 @@ export class ProcessTerminal implements Terminal {
 	#appearance: TerminalAppearance | undefined;
 	#osc11Pending = false;
 	#osc11ActiveToken?: TerminalAppearanceRequestToken;
-	#osc11QueuedQuery?: { route: Osc11QueryRoute; token?: TerminalAppearanceRequestToken };
+	#osc11QueuedQuery?: { cache?: TerminalMultiplexerBackgroundColorCache; token?: TerminalAppearanceRequestToken };
 	#nextAppearanceRequestToken = 1;
 	#osc11ResponseBuffer = "";
-	#osc11TmuxRefreshTimer?: Timer;
+	#osc11CacheRefreshTimer?: Timer;
 	#osc99PendingId: string | undefined;
 	#osc99ResponseBuffer = "";
 	#osc99Capabilities = new Map<string, string>();
@@ -845,9 +874,15 @@ export class ProcessTerminal implements Terminal {
 	#glyphProtocolReplyBuffer = "";
 	#glyphProtocolResult: boolean | undefined;
 	#glyphProtocolCallbacks: GlyphProtocolReportHandler[] = [];
+	#sixelSupport: boolean | undefined;
+	#sixelSupportCallbacks: Array<(supported: boolean) => void> = [];
 	#tspPending = false;
 	#tspResult: TspHello | null | undefined;
 	#tspCallbacks: TspHelloHandler[] = [];
+	/** Hello deadline inside tmux, where no DA1 sentinel can end the probe. */
+	#tspTimeout: NodeJS.Timeout | undefined;
+	/** This tmux pane's APC titles are off for TSP and must be restored. */
+	#tspTmuxPaneGated = false;
 	#tspReplyBuffer = "";
 	#privateCsiResponseBuffer = "";
 	#da1SentinelOwners: Da1SentinelOwner[] = [];
@@ -931,10 +966,11 @@ export class ProcessTerminal implements Terminal {
 
 	/**
 	 * Re-query the terminal background through the startup DA1-sentinel FIFO,
-	 * pending/queued gating, parsing, dedup, and appearance callbacks. Inside
-	 * tmux, only this explicit path first passes an OSC 11 query to the outer
-	 * terminal, waits briefly for tmux to consume the response into its cache,
-	 * then reads that cache with a direct query. The outer query deliberately has
+	 * pending/queued gating, parsing, dedup, and appearance callbacks. Inside a
+	 * multiplexer that answers OSC 11 from a cache (tmux), only this explicit
+	 * path first passes an OSC 11 query to the outer terminal, waits briefly for
+	 * the multiplexer to consume the response into its cache, then reads that
+	 * cache with a direct query. The outer query deliberately has
 	 * no DA1 sentinel: multiplexers can decode a fragmented DA1 response as a key
 	 * sequence and leak the remaining bytes into the editor. Startup and Mode 2031
 	 * probes remain direct. Suppressed while inactive, headless, or after teardown.
@@ -945,7 +981,10 @@ export class ProcessTerminal implements Terminal {
 		if (token >= this.#nextAppearanceRequestToken) {
 			this.#nextAppearanceRequestToken = token + 1;
 		}
-		this.#queryBackgroundColor(isInsideTmux() ? "tmux" : "direct", token);
+		const cache = terminalMultiplexerSessions().find(
+			multiplexer => multiplexer.backgroundColorCache,
+		)?.backgroundColorCache;
+		this.#queryBackgroundColor(cache, token);
 		return token;
 	}
 
@@ -960,6 +999,11 @@ export class ProcessTerminal implements Terminal {
 		if (this.#glyphProtocolResult !== undefined) callback(this.#glyphProtocolResult);
 	}
 
+	onSixelSupport(callback: (supported: boolean) => void): void {
+		this.#sixelSupportCallbacks.push(callback);
+		if (this.#sixelSupport !== undefined) callback(this.#sixelSupport);
+	}
+
 	onTspHello(callback: TspHelloHandler): void {
 		this.#tspCallbacks.push(callback);
 		if (this.#tspResult !== undefined) callback(this.#tspResult);
@@ -1099,6 +1143,8 @@ export class ProcessTerminal implements Terminal {
 		// events that lose modifier information. Must run after setRawMode(true)
 		// since that resets console mode flags.
 		this.#enableWindowsVTInput();
+		// Every response-eliciting probe goes out inside the leak guard.
+		this.#safeWrite(PROBE_GUARD_BEGIN);
 		// Query and enable Kitty keyboard protocol
 		// The query handler intercepts input temporarily, then installs the user's handler
 		// See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
@@ -1161,6 +1207,7 @@ export class ProcessTerminal implements Terminal {
 		for (const mode of XTERM_SCROLL_TO_BOTTOM_MODES) {
 			this.#queryPrivateMode(mode);
 		}
+		this.#safeWrite(PROBE_GUARD_END);
 	}
 
 	/**
@@ -1241,6 +1288,7 @@ export class ProcessTerminal implements Terminal {
 
 		// DA1 (Primary Device Attributes) response: \x1b[?...c
 		const da1ResponsePattern = /^\x1b\[\?[\d;]*c$/;
+		const da1SixelAttributePattern = /;4(?:;|c$)/u;
 
 		// Private CSI partial: \x1b[?<digits/semicolons>... — incomplete probe response
 		// that the StdinBuffer flushed before the terminator arrived (split across
@@ -1384,6 +1432,19 @@ export class ProcessTerminal implements Terminal {
 			// outstanding sentinel — a reply that arrives after the FIFO drains (slow
 			// SSH/PTY links) must never reach the composer as literal text (#8542).
 			if (da1ResponsePattern.test(sequence)) {
+				// Publish graphics support without forwarding DA1 bytes to application
+				// input or changing ownership of the existing probe sentinel.
+				const supportsSixel = da1SixelAttributePattern.test(sequence);
+				if (supportsSixel !== this.#sixelSupport) {
+					this.#sixelSupport = supportsSixel;
+					for (const callback of this.#sixelSupportCallbacks) {
+						try {
+							callback(supportsSixel);
+						} catch {
+							// Capability subscribers must not interrupt sentinel handling.
+						}
+					}
+				}
 				const owner = this.#da1SentinelOwners.shift();
 				if (!owner) {
 					// Late/unowned reply: nothing to resolve, just drop the bytes.
@@ -1406,7 +1467,7 @@ export class ProcessTerminal implements Terminal {
 						) {
 							const query = this.#osc11QueuedQuery;
 							this.#osc11QueuedQuery = undefined;
-							this.#startOsc11Query(query.route, query.token);
+							this.#startOsc11Query(query.cache, query.token);
 						}
 						break;
 					}
@@ -1624,36 +1685,39 @@ export class ProcessTerminal implements Terminal {
 	 * DA1 avoids indefinite hangs: if DA1 response arrives before OSC 11,
 	 * the terminal does not support OSC 11.
 	 */
-	#queryBackgroundColor(route: Osc11QueryRoute = "direct", token?: TerminalAppearanceRequestToken): void {
+	#queryBackgroundColor(
+		cache?: TerminalMultiplexerBackgroundColorCache,
+		token?: TerminalAppearanceRequestToken,
+	): void {
 		if (this.#dead) return;
 		// Queue if an OSC 11 query is in flight or its DA1 sentinel hasn't been
 		// consumed yet. Starting a new query while a DA1 is outstanding would
 		// increment the sentinel counter, and the old DA1 arrival would then
 		// prematurely clear the new query's pending state. Preserve a requested
-		// tmux passthrough route when coalescing direct and explicit queries, and
-		// retain the latest explicit request identity across automatic queries.
+		// cache refresh when coalescing direct and explicit queries, and retain
+		// the latest explicit request identity across automatic queries.
 		if (this.#osc11Pending || this.#da1SentinelOwners.some(o => o.kind === "osc11")) {
 			const queued = this.#osc11QueuedQuery;
-			this.#osc11QueuedQuery = {
-				route: queued?.route === "tmux" || route === "tmux" ? "tmux" : "direct",
-				token: token ?? queued?.token,
-			};
+			this.#osc11QueuedQuery = { cache: queued?.cache ?? cache, token: token ?? queued?.token };
 			return;
 		}
-		this.#startOsc11Query(route, token);
+		this.#startOsc11Query(cache, token);
 	}
 
-	#startOsc11Query(route: Osc11QueryRoute, token?: TerminalAppearanceRequestToken): void {
+	#startOsc11Query(
+		cache: TerminalMultiplexerBackgroundColorCache | undefined,
+		token?: TerminalAppearanceRequestToken,
+	): void {
 		this.#osc11Pending = true;
 		this.#osc11ActiveToken = token;
 		this.#osc11ResponseBuffer = "";
-		if (route === "tmux") {
-			this.#safeWrite(wrapTmuxPassthrough("\x1b]11;?\x07"));
-			this.#osc11TmuxRefreshTimer = setTimeout(() => {
-				this.#osc11TmuxRefreshTimer = undefined;
+		if (cache) {
+			this.#safeWrite(cache.passthrough("\x1b]11;?\x07"));
+			this.#osc11CacheRefreshTimer = setTimeout(() => {
+				this.#osc11CacheRefreshTimer = undefined;
 				if (this.#dead || !this.#osc11Pending) return;
 				this.#startDirectOsc11Query();
-			}, TMUX_OSC11_CACHE_REFRESH_DELAY_MS);
+			}, cache.settleMs);
 			return;
 		}
 		this.#startDirectOsc11Query();
@@ -1776,6 +1840,9 @@ export class ProcessTerminal implements Terminal {
 	#shouldQueryTspSupport(): boolean {
 		const override = $env.PI_TUI_NATIVE;
 		if (override === "0") return false;
+		// 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;
@@ -1793,16 +1860,37 @@ export class ProcessTerminal implements Terminal {
 			return;
 		}
 		this.#tspPending = true;
+		if (tmuxMultiplexer.isInside($env)) {
+			// tmux answers DA1 itself, ahead of any reply: wait for the reply instead.
+			this.#tspTmuxPaneGated = true;
+			setTmuxPaneApcTitles(false, $env);
+			this.#tspTimeout = setTimeout(() => {
+				this.#tspTimeout = undefined;
+				this.#resolveTspSupport(null);
+			}, TSP_TMUX_HELLO_TIMEOUT_MS);
+			this.#safeWrite(encodeTspHelloQuery());
+			return;
+		}
 		this.#da1SentinelOwners.push({ kind: "tsp" });
 		this.#safeWrite(`${encodeTspHelloQuery()}\x1b[c`);
 	}
 
+	/** Hand APC titles back to tmux once this pane stops speaking TSP. */
+	#endTspTmuxPane(): void {
+		clearTimeout(this.#tspTimeout);
+		this.#tspTimeout = undefined;
+		if (!this.#tspTmuxPaneGated) return;
+		this.#tspTmuxPaneGated = false;
+		setTmuxPaneApcTitles(true, $env);
+	}
+
 	#handleTspMessage(sequence: string): void {
 		const message = parseTspMessage(sequence);
-		if (message?.verb === "r") {
-			if (message.reply.r === "hello") this.#resolveTspSupport(message.reply);
+		if (message?.verb === "r" && message.reply.r === "hello") {
+			this.#resolveTspSupport(message.reply);
 			return;
 		}
+		// Events and every other reply (`blobs`) go to the native backend.
 		this.#inputHandler?.(sequence);
 	}
 
@@ -1811,6 +1899,12 @@ export class ProcessTerminal implements Terminal {
 		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.#endTspTmuxPane();
+		} else {
+			clearTimeout(this.#tspTimeout);
+			this.#tspTimeout = undefined;
+		}
 		this.#tspResult = result;
 		for (const cb of this.#tspCallbacks) {
 			try {
@@ -2176,9 +2270,9 @@ export class ProcessTerminal implements Terminal {
 			clearTimeout(this.#mode2031DebounceTimer);
 			this.#mode2031DebounceTimer = undefined;
 		}
-		if (this.#osc11TmuxRefreshTimer) {
-			clearTimeout(this.#osc11TmuxRefreshTimer);
-			this.#osc11TmuxRefreshTimer = undefined;
+		if (this.#osc11CacheRefreshTimer) {
+			clearTimeout(this.#osc11CacheRefreshTimer);
+			this.#osc11CacheRefreshTimer = undefined;
 		}
 		this.#appearanceCallbacks = [];
 		this.#appearanceReportCallbacks = [];
@@ -2195,8 +2289,11 @@ export class ProcessTerminal implements Terminal {
 		this.#glyphProtocolResult = undefined;
 		this.#glyphProtocolReplyBuffer = "";
 		this.#glyphProtocolCallbacks = [];
+		this.#sixelSupport = undefined;
+		this.#sixelSupportCallbacks = [];
 		setTerminalGlyphProtocol(false);
 		this.#tspPending = false;
+		this.#endTspTmuxPane();
 		this.#tspResult = undefined;
 		this.#tspReplyBuffer = "";
 		this.#tspCallbacks = [];
@@ -2366,11 +2463,14 @@ export class ProcessTerminal implements Terminal {
 			this.#trackStdoutBacklog(pending);
 			return;
 		}
-		// A console-sharing child process may have flipped the console codepage
-		// away from UTF-8; repair it before any bytes hit WriteFile so no frame
-		// is ever translated through an OEM codepage. See ensureWindowsConsoleUtf8.
-		if (process.platform === "win32") ensureWindowsConsoleUtf8();
+		// Without the pump, writes (and the codepage guard's console calls) block
+		// the event loop until the terminal drains; label them for the watchdog.
+		pushLoopPhase("ui.terminal-write");
 		try {
+			// A console-sharing child process may have flipped the console codepage
+			// away from UTF-8; repair it before any bytes hit WriteFile so no frame
+			// is ever translated through an OEM codepage. See ensureWindowsConsoleUtf8.
+			if (process.platform === "win32") ensureWindowsConsoleUtf8();
 			// Windows ConPTY drops viewport tracking when a single write exceeds
 			// ~32-64 KB: the host UI's scroll position stays parked at wherever
 			// the write began, even though every byte landed in scrollback. Split
@@ -2399,6 +2499,8 @@ export class ProcessTerminal implements Terminal {
 			this.#trackStdoutBacklog(process.stdout.writableLength ?? 0);
 		} catch (err) {
 			this.#markTerminalDisconnected("stdout failed", err);
+		} finally {
+			popLoopPhase();
 		}
 	}
 

package/src/theme/active-symbols.d.ts

@@ -1,7 +1,7 @@
 /**
  * Active theme's symbol lookup without importing `./theme` (which pulls the
  * native addon through `@linxiraos/pi-natives`). Key-hint formatting runs on
- * CLI paths that must stay addon-free (`omp --version`, help), so it reads the
+ * CLI paths that must stay addon-free (`zetacode --version`, help), so it reads the
  * active theme through this mirror; `./theme` publishes every assignment here.
  */
 import { type SymbolKey } from "./symbols";

package/src/theme/active-symbols.ts

@@ -1,7 +1,7 @@
 /**
  * Active theme's symbol lookup without importing `./theme` (which pulls the
  * native addon through `@linxiraos/pi-natives`). Key-hint formatting runs on
- * CLI paths that must stay addon-free (`omp --version`, help), so it reads the
+ * CLI paths that must stay addon-free (`zetacode --version`, help), so it reads the
  * active theme through this mirror; `./theme` publishes every assignment here.
  */
 import { SYMBOL_PRESETS, type SymbolKey } from "./symbols";

package/src/theme/schema-validation.ts

@@ -13,6 +13,7 @@ const themeColorsSchema = type({
 	muted: "string | number",
 	dim: "string | number",
 	text: "string | number",
+	"assistantMessageText?": "string | number",
 	thinkingText: "string | number",
 	selectedBg: "string | number",
 	userMessageBg: "string | number",