@linxiraos/pi-tui 1.1.27 → 1.2.1

package/src/terminal-capabilities.ts

@@ -10,12 +10,17 @@ import {
 	renderKittyPlaceholderLines,
 	setKittyGraphics,
 } from "./kitty-graphics";
-import { isInsideHerdr, isInsideTerminalMultiplexer } from "./terminal-multiplexer";
-import { isInsideTmux, resolveTmuxClientTerminalName, wrapTmuxPassthrough, wrapTmuxPassthroughIfNeeded } from "./tmux";
+import {
+	isInsideTerminalMultiplexer,
+	routeTerminalMultiplexerNotification,
+	terminalMultiplexerForTerm,
+	terminalMultiplexerSessions,
+} from "./terminal-multiplexer";
+import { resolveTmuxClientTerminalName, wrapTmuxPassthroughIfNeeded } from "./tmux";
 import type { HangulCompatibilityJamoWidth } from "./utils";
 
 export * from "./terminal-multiplexer";
-export { isInsideTmux, wrapTmuxPassthrough } from "./tmux";
+export { wrapTmuxPassthrough } from "./tmux";
 
 export enum ImageProtocol {
 	Kitty = "\x1b_G",
@@ -45,92 +50,6 @@ export type TerminalId =
 	| "base"
 	| "trueColor";
 
-const CMUX_NOTIFICATION_TITLE = "zeta";
-const CMUX_SURFACE_ID_PATTERN = /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/iu;
-
-/** Title and body for an out-of-band multiplexer notification (cmux, Herdr). */
-function notificationTitleAndBody(message: string | TerminalNotification): { title: string; body: string } {
-	if (typeof message === "string") return { title: CMUX_NOTIFICATION_TITLE, body: message };
-	return { title: message.title?.trim() || CMUX_NOTIFICATION_TITLE, body: message.body ?? "" };
-}
-
-/**
- * Route a notification through cmux when the process belongs to a concrete
- * surface. Workspace/socket state alone is not enough: only the injected
- * surface UUID identifies the pane that should receive the notification.
- * Returns whether cmux owns delivery so the caller can preserve every existing
- * terminal fallback unchanged when no valid surface is present.
- */
-function sendCmuxNotification(message: string | TerminalNotification, env: NodeJS.ProcessEnv = Bun.env): boolean {
-	const surfaceId = env.CMUX_SURFACE_ID?.trim();
-	if (!surfaceId || !CMUX_SURFACE_ID_PATTERN.test(surfaceId)) return false;
-
-	const { title, body } = notificationTitleAndBody(message);
-	try {
-		const child = Bun.spawn({
-			cmd: ["cmux", "notify", "--surface", surfaceId, "--title", title, "--body", body],
-			stdin: "ignore",
-			stdout: "ignore",
-			stderr: "ignore",
-		});
-		child.unref();
-	} catch {
-		// A missing cmux binary leaves delivery to the existing terminal fallback.
-		return false;
-	}
-	return true;
-}
-
-const HERDR_PANE_ID_PATTERN = /^[0-9A-Za-z:_-]{1,64}$/u;
-/**
- * `herdr notification show` takes the title as its first positional and reads
- * exactly these three values there as a help request; it has no `--`
- * terminator. Any other text, including one starting with `-`, is a title.
- */
-const HERDR_USAGE_TOKENS = new Set(["help", "--help", "-h"]);
-
-/**
- * Route a notification through Herdr when the process runs inside one of its
- * panes. Herdr multiplexes panes like tmux but swallows bare OSC 9 / OSC 99 and
- * has no DCS passthrough envelope, and its bell relay does not flag a
- * backgrounded tab — so without this branch a backgrounded pane gets no signal
- * at all that the agent finished or is waiting for input.
- *
- * `sound` maps the notification kind onto what Herdr offers: a question waiting
- * on the user and a turn that stopped with an error both need the human and
- * ring `request`, a settled turn rings `done`, anything else stays
- * silent. Returns whether Herdr owns delivery, so every existing terminal
- * fallback is preserved when the pane id is absent or the binary is missing.
- */
-function sendHerdrNotification(message: string | TerminalNotification, env: NodeJS.ProcessEnv = Bun.env): boolean {
-	// Pane-only detection, like `isInsideHerdr`: an env-sanitizing launcher can
-	// drop HERDR_ENV and keep the pane identity, and that pane can still be
-	// backgrounded. The pane id itself is what the CLI needs, so it stays required.
-	if (!isInsideHerdr(env)) return false;
-	const paneId = env.HERDR_PANE_ID?.trim();
-	if (!paneId || !HERDR_PANE_ID_PATTERN.test(paneId)) return false;
-
-	const parsed = notificationTitleAndBody(message);
-	const title = HERDR_USAGE_TOKENS.has(parsed.title) ? CMUX_NOTIFICATION_TITLE : parsed.title;
-	const body = parsed.body;
-	const kinds = typeof message === "string" ? [] : [message.type ?? []].flat();
-	const sound =
-		kinds.includes("ask") || kinds.includes("error") ? "request" : kinds.includes("completion") ? "done" : "none";
-	try {
-		const child = Bun.spawn({
-			cmd: ["herdr", "notification", "show", title, "--body", body, "--sound", sound],
-			stdin: "ignore",
-			stdout: "ignore",
-			stderr: "ignore",
-		});
-		child.unref();
-	} catch {
-		// A missing herdr binary leaves delivery to the existing terminal fallback.
-		return false;
-	}
-	return true;
-}
-
 const IMAGE_MARKER_SCAN_LIMIT = 512;
 const SIXEL_MARKER_SCAN_LIMIT = 128;
 const KITTY_PLACEHOLDER_HIGH_SURROGATE = KITTY_PLACEHOLDER.charCodeAt(0);
@@ -236,33 +155,16 @@ export class TerminalInfo {
 
 	sendNotification(message: string | TerminalNotification): void {
 		if (isNotificationSuppressed() || isTerminalHeadless()) return;
-		// Innermost surface first. A Herdr pane launched inside a cmux surface
-		// inherits both `HERDR_PANE_ID` and the outer `CMUX_SURFACE_ID`; routing to
-		// cmux there would flag the containing surface and leave the backgrounded
-		// Herdr pane — the one actually waiting — without a sound or a marker.
-		if (sendHerdrNotification(message)) return;
-		if (sendCmuxNotification(message)) return;
 		const formatted = this.formatNotification(message);
-		// Under tmux, terminals whose notify protocol is OSC 9 / OSC 99 would
-		// otherwise lose the notification entirely: tmux does not forward bare
-		// OSC 9/99 to the outer terminal, and the bare sequence does not flag
-		// tmux's own `monitor-bell` / `monitor-activity`. Wrap the OSC in tmux's
-		// DCS passthrough envelope so users with `allow-passthrough on` still
-		// get the desktop toast, then append a BEL so `monitor-bell` flags the
-		// pane/window for everyone else — the only signal a backgrounded pane
-		// has that the agent finished or is waiting for input. `Bell` protocol
-		// already self-flags via tmux's bell monitoring, so leave it alone.
-		if (this.notifyProtocol !== NotifyProtocol.Bell && isInsideTmux()) {
-			writeTerminalSequence(`${wrapTmuxPassthrough(formatted)}\x07`);
-			return;
-		}
-		// Zellij drops OSC 9/99 and has no DCS passthrough envelope, but raises its
-		// `[!]` bell flag on a bare BEL — the same backgrounded-pane signal tmux
-		// users get. So follow the (Zellij-swallowed) OSC with a plain BEL.
-		if (this.notifyProtocol !== NotifyProtocol.Bell && isInsideZellij()) {
-			writeTerminalSequence(`${formatted}\x07`);
-			return;
-		}
+		// Multiplexers that swallow or rewrite the terminal's notification get it
+		// first, innermost target first; the terminal sequence is the fallback.
+		const routed = routeTerminalMultiplexerNotification({
+			message,
+			env: Bun.env,
+			sequence: this.notifyProtocol === NotifyProtocol.Bell ? null : formatted,
+			write: writeTerminalSequence,
+		});
+		if (routed) return;
 		writeTerminalSequence(formatted);
 		// VTE-family terminals (Ptyxis, GNOME Terminal, Tilix, …) plus Alacritty
 		// and bare xterm-on-Wayland have no in-band escape that surfaces an
@@ -276,15 +178,6 @@ export class TerminalInfo {
 	}
 }
 
-/**
- * Whether the agent process is running inside a Zellij session. Read fresh on
- * each call (like {@link isInsideTmux}) so a session attached/detached mid-run
- * is observed and tests can toggle `Bun.env.ZELLIJ` per case.
- */
-export function isInsideZellij(env: NodeJS.ProcessEnv = Bun.env): boolean {
-	return Boolean(env.ZELLIJ);
-}
-
 /**
  * Whether the agent process runs in an SSH session, so the terminal emulator
  * is remote and host-local input/keyboard modes cannot be assumed.
@@ -381,12 +274,12 @@ function advertisesSynchronizedOutput(termFeatures: string | undefined): boolean
  *   2. Positive `TERM_FEATURES` advertisement (`Sy`) — survives SSH/mux wrapping.
  *   3. Windows Terminal (1.24+) via `WT_SESSION`, on native win32 and the
  *      WSL/SSH-fronted host alike.
- *   4. Herdr panes. Herdr is otherwise treated as a multiplexer so leaked
- *      kitty/ghostty identities cannot enable placeholder graphics, but its
- *      pane VTE is libghostty and already suppresses compositing while DEC 2026
- *      is set. Leaving sync off lets CUP-diff paints and split write(2) chunks
- *      composite as dirty-row patches — the live viewport tears, with the top
- *      frozen while only the bottom refreshes.
+ *   4. A multiplexer session whose pane VTE honors DEC 2026 regardless of its
+ *      DECRQM reply (Herdr's libghostty pane). Such a multiplexer still owns
+ *      the grid, so leaked kitty/ghostty identities cannot enable placeholder
+ *      graphics, but leaving sync off lets CUP-diff paints and split write(2)
+ *      chunks composite as dirty-row patches — the live viewport tears, with
+ *      the top frozen while only the bottom refreshes.
  *   5. Known direct terminals with confirmed support. SSH does *not* disable —
  *      DEC 2026 passes through SSH when the outer terminal honors it.
  *   6. Everything else starts off, including risky multiplexers; the runtime
@@ -402,7 +295,7 @@ export function shouldEnableSynchronizedOutputByDefault(
 
 	if (advertisesSynchronizedOutput(env.TERM_FEATURES)) return true;
 	if (env.WT_SESSION && (!env.TERM_PROGRAM || env.TERM_PROGRAM.toLowerCase() === "windows_terminal")) return true;
-	if (isInsideHerdr(env)) return true;
+	if (terminalMultiplexerSessions(env).some(multiplexer => multiplexer.honorsSynchronizedOutput)) return true;
 
 	// Risky multiplexers start off even when an inner terminal id leaks through:
 	// older tmux/screen synchronized-output handling is flaky and a mux may not
@@ -521,48 +414,35 @@ export function hyperlinksUserOverride(env: NodeJS.ProcessEnv = Bun.env): boolea
 	return null;
 }
 
-/**
- * Parse tmux's self-reported version from `TERM_PROGRAM_VERSION`. tmux sets
- * `TERM_PROGRAM=tmux` and `TERM_PROGRAM_VERSION=<version>` automatically since
- * 3.2a; older releases (or any path that does not surface the version) yield
- * `null` and the caller treats tmux conservatively.
- */
-function parseTmuxVersionFromEnv(env: NodeJS.ProcessEnv): { major: number; minor: number } | null {
-	if (env.TERM_PROGRAM?.toLowerCase() !== "tmux") return null;
-	return parseMajorMinorVersion(env.TERM_PROGRAM_VERSION);
-}
-
 /**
  * Whether OSC 8 hyperlinks should be enabled by default.
  *
  * Policy (highest precedence first):
  *   1. Explicit user override (`PI_NO_HYPERLINKS=1` off, `PI_FORCE_HYPERLINKS=1`
  *      on). Opt-out wins ties.
- *   2. Herdr pane with no nested screen/tmux: on. Herdr hides the outer
- *      terminal (`TERM=xterm-256color`, no `TERM_PROGRAM`), but it renders
- *      OSC 8 in its own grid and opens links itself on Ctrl+click, so the
- *      outer terminal's support does not matter.
+ *   2. Every multiplexer session with a hyperlink policy renders OSC 8 itself
+ *      (`render`, e.g. Herdr): on. Herdr hides the outer terminal
+ *      (`TERM=xterm-256color`, no `TERM_PROGRAM`), so the outer terminal's
+ *      support does not matter.
  *   2b. Zeta workbench pane with no nested screen/tmux: on, for the same
  *      reason — the workbench's terminal simulator renders OSC 8 itself and
  *      opens links on Ctrl+click (`ZETA_WORKBENCH=1` is injected into every
  *      pane PTY; the outer terminal is invisible from inside).
  *   3. Static terminal capability — terminals whose {@link TerminalInfo} marks
  *      `hyperlinks: false` (e.g. `base`) stay off unless the user forced on.
- *   4. GNU screen's explicit session marker (`STY`) always off, even if tmux is
- *      also present: a screen layer anywhere in the path cannot forward OSC 8.
- *   5. tmux session (`TMUX` set): enabled when tmux self-reports >= 3.4 via
- *      `TERM_PROGRAM_VERSION` (tmux 3.4 stores OSC 8 as a cell attribute and
- *      forwards it to outer terminals whose `terminal-features` include
- *      `hyperlinks`). Older or unknown versions stay off; on outer terminals
- *      without the feature configured, tmux silently drops the sequence —
- *      identical to today. Checked before the screen-family TERM heuristic
- *      because tmux's historical `default-terminal` is `screen-256color`, so
- *      `TERM=screen*` inside a tmux session must NOT short-circuit to off.
- *   6. screen-family TERM without `TMUX` always off: screen never gained OSC 8
- *      support.
- *   7. tmux-family TERM without `TMUX` env — unusual (e.g. inspection scripts);
- *      no version available, so off.
- *   8. Otherwise honor the static terminal capability.
+ *   4. A session that never forwards OSC 8 (`drop`, e.g. GNU screen's `STY`)
+ *      always off, even when a forwarding multiplexer is also present.
+ *   5. Forwarding sessions (`forward`, e.g. `TMUX`): enabled when every one
+ *      self-reports at least its forwarding version via `TERM_PROGRAM` /
+ *      `TERM_PROGRAM_VERSION` (tmux 3.4). Older or unknown versions stay off;
+ *      on outer terminals without the feature configured, tmux silently drops
+ *      the sequence. Checked before the TERM heuristic because tmux's
+ *      historical `default-terminal` is `screen-256color`, so `TERM=screen*`
+ *      inside a tmux session must NOT short-circuit to off.
+ *   6. TERM naming a multiplexer whose session markers were stripped: off,
+ *      since no session proves the multiplexer forwards OSC 8 (screen never
+ *      does; tmux has no version to check).
+ *   7. Otherwise honor the static terminal capability.
  */
 export function shouldEnableHyperlinksByDefault(
 	env: NodeJS.ProcessEnv = Bun.env,
@@ -571,29 +451,29 @@ export function shouldEnableHyperlinksByDefault(
 	const override = hyperlinksUserOverride(env);
 	if (override !== null) return override;
 
-	if (isInsideHerdr(env) && !env.STY && !env.TMUX) return true;
+	const policies = terminalMultiplexerSessions(env).flatMap(multiplexer =>
+		multiplexer.hyperlinks === undefined ? [] : [multiplexer.hyperlinks],
+	);
+	if (policies.length > 0 && policies.every(policy => policy === "render")) return true;
 
 	if (isInsideZetaWorkbench(env) && !env.STY && !env.TMUX) return true;
 
 	if (!getTerminalInfo(terminalId).hyperlinks) return false;
 
-	// STY is GNU screen's explicit session marker. It vetoes tmux enabling when
-	// multiplexers are nested because screen cannot forward OSC 8 anywhere in the
-	// path.
-	if (env.STY) return false;
-
-	// tmux check before TERM heuristics: TMUX is the authoritative current-session
-	// signal and supersedes TERM, which may be `screen-256color` under tmux's
-	// historical default-terminal setting.
-	if (env.TMUX) {
-		const version = parseTmuxVersionFromEnv(env);
-		if (!version) return false;
-		return version.major > 3 || (version.major === 3 && version.minor >= 4);
+	if (policies.includes("drop")) return false;
+
+	const forwarders = policies.flatMap(policy => (typeof policy === "object" ? [policy.forward] : []));
+	if (forwarders.length > 0) {
+		const termProgram = env.TERM_PROGRAM?.toLowerCase();
+		return forwarders.every(forward => {
+			if (termProgram !== forward.termProgram) return false;
+			const version = parseMajorMinorVersion(env.TERM_PROGRAM_VERSION);
+			if (!version) return false;
+			return version.major > forward.major || (version.major === forward.major && version.minor >= forward.minor);
+		});
 	}
 
-	const term = env.TERM?.toLowerCase() ?? "";
-	if (term.startsWith("screen")) return false;
-	if (term.startsWith("tmux")) return false;
+	if (terminalMultiplexerForTerm(env)) return false;
 
 	return true;
 }
@@ -667,10 +547,14 @@ export function resolveImageProtocol(
 	if (imageProtocol !== null && isPaseoEmbedder(env)) {
 		return null;
 	}
-	// Herdr owns the pane grid but does not expose whether the attached client
-	// enabled its experimental Kitty renderer. Outer-terminal identity variables
-	// can leak into the pane, so only the explicit protocol override is safe.
-	if (imageProtocol !== null && isInsideHerdr(env)) {
+	// Some multiplexers own the pane grid without exposing whether the attached
+	// client renders graphics (Herdr's experimental Kitty renderer). Outer-
+	// terminal identity variables can leak into the pane, so only the explicit
+	// protocol override is safe.
+	if (
+		imageProtocol !== null &&
+		terminalMultiplexerSessions(env).some(multiplexer => multiplexer.imagesRequireOverride)
+	) {
 		return null;
 	}
 	return imageProtocol;
@@ -1050,8 +934,7 @@ export function encodeKittyPlacement(options: {
 /**
  * Exact shape of the direct-placement line {@link Image} emits as its block's
  * last row: optional `ESC 7` + `CUU(rows-1)` prefix, the {@link encodeKittyPlacement}
- * APC, optional `ESC 8` suffix. tmux-passthrough-wrapped lines deliberately do
- * not match (passthrough placements stay untouched).
+ * APC, optional `ESC 8` suffix. The parser unwraps tmux passthrough first.
  */
 const KITTY_DIRECT_PLACEMENT_LINE =
 	/^(?:\x1b7(?:\x1b\[(\d+)A)?)?\x1b_Ga=p,q=2,C=1,i=(\d+)(?:,p=(\d+))?(?:,c=(\d+))?(?:,r=(\d+))?\x1b\\(?:\x1b8)?$/;
@@ -1066,10 +949,15 @@ export interface ParsedKittyPlacementLine {
 /**
  * Parse a frame line that consists solely of a Kitty direct placement (the
  * last line of an {@link Image} block). Returns null for anything else —
- * placeholder grids, tmux-wrapped placements, sixel/iTerm2 payloads — so
+ * placeholder grids, sixel/iTerm2 payloads — so
  * callers fall back to writing the line verbatim.
  */
 export function parseKittyDirectPlacementLine(line: string): ParsedKittyPlacementLine | null {
+	if (line.includes("\x1bPtmux;")) {
+		line = line.replace(/\x1bPtmux;((?:[^\x1b]|\x1b\x1b)*)\x1b\\/g, (_match, payload: string) =>
+			payload.replaceAll("\x1b\x1b", "\x1b"),
+		);
+	}
 	const m = KITTY_DIRECT_PLACEMENT_LINE.exec(line);
 	if (!m) return null;
 	const columns = m[4] !== undefined ? Number(m[4]) : 0;
@@ -1114,9 +1002,7 @@ export function encodeKittyPlacementLine(options: {
 		const srcY = Math.floor((options.imageHeightPx * hiddenRows) / options.rows);
 		params.push(`y=${srcY}`, `h=${Math.max(1, options.imageHeightPx - srcY)}`);
 	}
-	// No tmux passthrough: inside tmux the component's own line arrives
-	// wrapped, never parses, and never reaches this rewrite.
-	const apc = `\x1b_G${params.join(",")}\x1b\\`;
+	const apc = wrapTmuxPassthroughIfNeeded(`\x1b_G${params.join(",")}\x1b\\`);
 	const cuu = visibleRows - 1;
 	return cuu > 0 ? `\x1b7\x1b[${cuu}A${apc}\x1b8` : apc;
 }
@@ -1143,8 +1029,8 @@ export function encodeKittyDeleteAllImages(): string {
 /**
  * Delete a single placement of an image (`d=i`, lowercase): removes its cells
  * and registry entry but keeps the transmitted data, so a later `a=p` under a
- * fresh placement id needs no retransmit. Used to clear stale placement-epoch
- * entries after a destructive history clear.
+ * fresh placement id needs no retransmit. The frame writer uses this before
+ * replacing a live image without deleting its archived copies.
  */
 export function encodeKittyDeletePlacement(imageId: number, placementId: number): string {
 	return wrapTmuxPassthroughIfNeeded(`\x1b_Ga=d,d=i,i=${imageId},p=${placementId},q=2\x1b\\`);

package/src/terminal-multiplexer.d.ts

@@ -1,20 +1,133 @@
-/** True when this process is running inside a Herdr pane. */
-export declare function isInsideHerdr(env?: NodeJS.ProcessEnv): boolean;
-/** Terminal multiplexers zeta recognizes as owning the screen grid. */
-export type TerminalMultiplexer = "herdr" | "tmux" | "screen" | "zellij" | "cmux" | "wmux";
+import type { TerminalMultiplexerModule, TerminalMultiplexerNotificationRequest } from "./multiplexers/types";
 /**
- * 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
+ * Every multiplexer omp recognizes, in classification order within each
+ * precedence tier. Adding a multiplexer means adding its module here.
+ */
+declare const registry: readonly [{
+    readonly id: "herdr";
+    readonly precedence: "session";
+    readonly sessionEnvKeys: readonly ["HERDR_ENV", "HERDR_PANE_ID", "HERDR_TAB_ID", "HERDR_WORKSPACE_ID"];
+    readonly ownsScreenGrid: true;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+    readonly notifier: {
+        readonly tier: "pane";
+        readonly send: ({ message, env }: TerminalMultiplexerNotificationRequest) => boolean;
+    };
+    readonly hyperlinks: "render";
+    readonly honorsSynchronizedOutput: true;
+    readonly imagesRequireOverride: true;
+}, {
+    readonly id: "tmux";
+    readonly precedence: "session";
+    readonly sessionEnvKeys: readonly ["TMUX"];
+    readonly termPrefix: "tmux";
+    readonly ownsScreenGrid: true;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+    readonly notifier: {
+        readonly tier: "inBand";
+        readonly send: ({ sequence, write }: TerminalMultiplexerNotificationRequest) => boolean;
+    };
+    readonly hyperlinks: {
+        readonly forward: {
+            readonly termProgram: "tmux";
+            readonly major: 3;
+            readonly minor: 4;
+        };
+    };
+    readonly backgroundColorCache: {
+        readonly passthrough: typeof import("./tmux").wrapTmuxPassthrough;
+        readonly settleMs: 100;
+    };
+    readonly expandsRepPadding: true;
+    readonly expiresSynchronizedOutput: true;
+    readonly altRestoreEndsSynchronizedOutput: true;
+    readonly growsBeforeSigwinch: true;
+}, {
+    readonly id: "screen";
+    readonly precedence: "session";
+    readonly sessionEnvKeys: readonly ["STY"];
+    readonly termPrefix: "screen";
+    readonly ownsScreenGrid: true;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+    readonly hyperlinks: "drop";
+}, {
+    readonly id: "zellij";
+    readonly precedence: "session";
+    readonly sessionEnvKeys: readonly ["ZELLIJ"];
+    readonly ownsScreenGrid: true;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+    readonly notifier: {
+        readonly tier: "inBand";
+        readonly send: ({ sequence, write }: TerminalMultiplexerNotificationRequest) => boolean;
+    };
+    readonly backgroundQueryBrokenOn: readonly ["darwin"];
+}, {
+    readonly id: "cmux";
+    readonly precedence: "session";
+    readonly sessionEnvKeys: readonly ["CMUX_WORKSPACE_ID", "CMUX_SURFACE_ID", "CMUX_REMOTE_TRANSPORT"];
+    readonly ownsScreenGrid: true;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+    readonly notifier: {
+        readonly tier: "surface";
+        readonly send: ({ message, env }: TerminalMultiplexerNotificationRequest) => boolean;
+    };
+}, {
+    readonly id: "wmux";
+    readonly precedence: "session";
+    readonly sessionEnvKeys: readonly ["WMUX", "WMUX_SURFACE_ID"];
+    readonly ownsScreenGrid: true;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+}, {
+    readonly id: "orca";
+    readonly precedence: "outerApp";
+    readonly sessionEnvKeys: readonly ["ORCA_PANE_KEY", "ORCA_WORKTREE_ID"];
+    readonly ownsScreenGrid: false;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+}];
+/** Terminal multiplexers omp recognizes. */
+export type TerminalMultiplexer = (typeof registry)[number]["id"];
+/** Every environment variable multiplexer classification reads, including the TERM fallback. */
+export declare const TERMINAL_MULTIPLEXER_ENV_KEYS: readonly string[];
+/**
+ * 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 declare function hasTerminalMultiplexerSession(multiplexer: TerminalMultiplexer, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Every multiplexer whose explicit session markers are present, in registry
+ * order. Nested sessions all appear; TERM is not consulted.
+ */
+export declare function terminalMultiplexerSessions(env?: NodeJS.ProcessEnv): TerminalMultiplexerModule<TerminalMultiplexer>[];
+/**
+ * The multiplexer TERM names, whether or not its session markers survived.
+ * This is classification's TERM fallback; session markers are not consulted.
+ */
+export declare function terminalMultiplexerForTerm(env?: NodeJS.ProcessEnv): TerminalMultiplexerModule<TerminalMultiplexer> | undefined;
+/**
+ * Registry entry for the multiplexer hosting the current process, or
+ * `undefined` for a direct terminal. Same precedence as
+ * {@link classifyTerminalMultiplexer}.
+ */
+export declare function classifyTerminalMultiplexerModule(env?: NodeJS.ProcessEnv): TerminalMultiplexerModule<TerminalMultiplexer> | undefined;
+/**
+ * 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 declare function classifyTerminalMultiplexer(env?: NodeJS.ProcessEnv): TerminalMultiplexer | null;
-/** True when a terminal multiplexer owns the current screen grid. */
+/** True when the classified multiplexer owns the current screen grid. */
 export declare function isInsideTerminalMultiplexer(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Offer a notification to every active session's notifier, innermost tier
+ * first. Returns whether one delivered it; otherwise the terminal fallback
+ * applies unchanged.
+ */
+export declare function routeTerminalMultiplexerNotification(request: TerminalMultiplexerNotificationRequest): boolean;
+export {};