@linxiraos/pi-tui 1.1.26 → 1.2.0

package/src/keybinding-matchers.ts

@@ -53,11 +53,15 @@ export function matchesSelectPageDown(data: string): boolean {
 	return getKeybindings().matches(data, "tui.select.pageDown");
 }
 
+/** Effective external-editor key: the first bound key, or Ctrl+G when unbound. */
+export function appExternalEditorKey(): KeyId {
+	return getKeybindings().getKeys("app.editor.external")[0] ?? "ctrl+g";
+}
+
 /** Match the external-editor keybinding, falling back to Ctrl+G when unbound. */
 export function matchesAppExternalEditor(data: string): boolean {
 	const keybindings = getKeybindings();
-	const externalEditorKeys = keybindings.getKeys("app.editor.external");
-	if (externalEditorKeys.length > 0) {
+	if (keybindings.getKeys("app.editor.external").length > 0) {
 		return keybindings.matches(data, "app.editor.external");
 	}
 	return matchesKey(data, "ctrl+g");

package/src/keybindings.d.ts

@@ -107,7 +107,7 @@ export declare const TUI_KEYBINDINGS: {
         readonly description: "Delete word backward";
     };
     readonly "tui.editor.deleteWordForward": {
-        readonly defaultKeys: ["alt+delete", "alt+d", "super+alt+delete", "super+alt+d"];
+        readonly defaultKeys: ["alt+delete", "alt+d", "ctrl+delete", "super+alt+delete", "super+alt+d"];
         readonly description: "Delete word forward";
     };
     readonly "tui.editor.deleteToLineStart": {

package/src/keybindings.ts

@@ -105,7 +105,7 @@ export const TUI_KEYBINDINGS = {
 		description: "Delete word backward",
 	},
 	"tui.editor.deleteWordForward": {
-		defaultKeys: ["alt+delete", "alt+d", "super+alt+delete", "super+alt+d"],
+		defaultKeys: ["alt+delete", "alt+d", "ctrl+delete", "super+alt+delete", "super+alt+d"],
 		description: "Delete word forward",
 	},
 	"tui.editor.deleteToLineStart": {

package/src/kitty-graphics.d.ts

@@ -30,8 +30,8 @@ export interface KittyGraphicsFeatures {
  * cannot use cursor-positioned placements because the outer terminal does not
  * know pane scroll/reflow state. An explicit `PI_FORCE_IMAGE_PROTOCOL=kitty`
  * opts into placeholders under any multiplexer — matching `timg -pk`.
- * Automatic Herdr fallback stays off because its pane marker does not prove
- * that the experimental Kitty renderer is enabled.
+ * Automatic fallback stays off inside multiplexers whose pane marker does not
+ * prove that a Kitty renderer is enabled (Herdr's is experimental).
  *
  * `PI_NO_KITTY_PLACEHOLDERS=1` and `PI_KITTY_PLACEHOLDERS=0` remain hard
  * opt-outs; `PI_KITTY_PLACEHOLDERS=1` explicitly opts in anywhere else.

package/src/kitty-graphics.ts

@@ -15,7 +15,7 @@
  * forms. Protocol gating (`imageProtocol === Kitty`) lives in the caller.
  */
 
-import { isInsideHerdr, isInsideTerminalMultiplexer } from "./terminal-multiplexer";
+import { isInsideTerminalMultiplexer, terminalMultiplexerSessions } from "./terminal-multiplexer";
 import { wrapTmuxPassthroughIfNeeded } from "./tmux";
 
 /** Kitty Unicode placeholder base character (U+10EEEE, Plane 16 PUA). */
@@ -67,8 +67,8 @@ export interface KittyGraphicsFeatures {
  * cannot use cursor-positioned placements because the outer terminal does not
  * know pane scroll/reflow state. An explicit `PI_FORCE_IMAGE_PROTOCOL=kitty`
  * opts into placeholders under any multiplexer — matching `timg -pk`.
- * Automatic Herdr fallback stays off because its pane marker does not prove
- * that the experimental Kitty renderer is enabled.
+ * Automatic fallback stays off inside multiplexers whose pane marker does not
+ * prove that a Kitty renderer is enabled (Herdr's is experimental).
  *
  * `PI_NO_KITTY_PLACEHOLDERS=1` and `PI_KITTY_PLACEHOLDERS=0` remain hard
  * opt-outs; `PI_KITTY_PLACEHOLDERS=1` explicitly opts in anywhere else.
@@ -81,8 +81,14 @@ export function detectKittyUnicodePlaceholdersSupport(terminalId: string, env: N
 	if (force === "0" || force === "false" || force === "off" || force === "no" || force === "n") return false;
 	const insideMultiplexer = isInsideTerminalMultiplexer(env);
 	if (insideMultiplexer && env.PI_FORCE_IMAGE_PROTOCOL?.trim().toLowerCase() === "kitty") return true;
-	if (isInsideHerdr(env)) return false;
-	return terminalId === "kitty" || terminalId === "ghostty" || terminalId === "otty" || terminalId === "rio";
+	if (terminalMultiplexerSessions(env).some(multiplexer => multiplexer.imagesRequireOverride)) return false;
+	return (
+		terminalId === "kitty" ||
+		terminalId === "ghostty" ||
+		terminalId === "monstar" ||
+		terminalId === "otty" ||
+		terminalId === "rio"
+	);
 }
 
 let features: KittyGraphicsFeatures = {

package/src/loop-watchdog.d.ts

@@ -21,13 +21,14 @@ interface LoopWatchdogTimer {
     cancel?(): void;
 }
 /**
- * Always-on event-loop lag probe. Each tick is scheduled `intervalMs` ahead of
- * a recorded deadline; a tick that fires `thresholdMs` past its deadline means
- * the loop was blocked that long. The overshoot is logged once on the rising
- * edge (one block ⇒ one line, deduped via `#wasBlocked`), tagged with the phase
- * active during the elapsed interval via {@link takeRecentLoopPhase} — which
- * survives the synchronous push/pop the instrumented hot paths do before this
- * delayed tick can run — so the stall names its cause instead of "unknown".
+ * Always-on event-loop lag probe. Each tick is scheduled `intervalMs` ahead,
+ * with that target recorded as its deadline; a tick that fires `thresholdMs`
+ * past its deadline means the loop was blocked that long. The overshoot is
+ * logged once on the rising edge (one block ⇒ one line, deduped via
+ * `#wasBlocked`). Attribution via
+ * {@link takeLoopPhaseAttribution} totals each innermost phase only after the tick's
+ * deadline. A phase is named, with `phaseMs`, only when its total outweighs all
+ * unlabeled time in that late window; otherwise the block remains "unknown".
  *
  * The handle is `unref`'d so the probe never keeps the process alive, and stop()
  * cancels the armed timer when the handle exposes `cancel` (the default

package/src/loop-watchdog.ts

@@ -1,5 +1,5 @@
 import { performance } from "node:perf_hooks";
-import { logger, takeRecentLoopPhase } from "@linxiraos/pi-utils";
+import { logger, resetLoopPhaseWindow, takeLoopPhaseAttribution } from "@linxiraos/pi-utils";
 
 export interface LoopWatchdogOptions {
 	/** How far ahead each probe tick is scheduled, in ms. Default 250. */
@@ -35,13 +35,14 @@ interface LoopWatchdogTimer {
 const CPU_BUSY_RATIO = 0.01;
 
 /**
- * Always-on event-loop lag probe. Each tick is scheduled `intervalMs` ahead of
- * a recorded deadline; a tick that fires `thresholdMs` past its deadline means
- * the loop was blocked that long. The overshoot is logged once on the rising
- * edge (one block ⇒ one line, deduped via `#wasBlocked`), tagged with the phase
- * active during the elapsed interval via {@link takeRecentLoopPhase} — which
- * survives the synchronous push/pop the instrumented hot paths do before this
- * delayed tick can run — so the stall names its cause instead of "unknown".
+ * Always-on event-loop lag probe. Each tick is scheduled `intervalMs` ahead,
+ * with that target recorded as its deadline; a tick that fires `thresholdMs`
+ * past its deadline means the loop was blocked that long. The overshoot is
+ * logged once on the rising edge (one block ⇒ one line, deduped via
+ * `#wasBlocked`). Attribution via
+ * {@link takeLoopPhaseAttribution} totals each innermost phase only after the tick's
+ * deadline. A phase is named, with `phaseMs`, only when its total outweighs all
+ * unlabeled time in that late window; otherwise the block remains "unknown".
  *
  * The handle is `unref`'d so the probe never keeps the process alive, and stop()
  * cancels the armed timer when the handle exposes `cancel` (the default
@@ -101,12 +102,15 @@ export class LoopWatchdog {
 	}
 
 	stop(): void {
+		// Attribution state is process-global: a watchdog that is not running must not disarm another's window.
+		if (!this.#running) return;
 		this.#running = false;
 		this.#wasBlocked = false;
 		this.#stallEndedAt = Number.NEGATIVE_INFINITY;
 		this.#generation++;
 		this.#handle?.cancel?.();
 		this.#handle = undefined;
+		resetLoopPhaseWindow();
 	}
 
 	/**
@@ -133,6 +137,7 @@ export class LoopWatchdog {
 	#armTick(): void {
 		const generation = this.#generation;
 		this.#expected = this.#now() + this.#intervalMs;
+		resetLoopPhaseWindow(this.#expected, this.#now);
 		this.#expectedCpu = this.#cpuNow();
 		this.#handle = this.#schedule(() => this.#tick(generation), this.#intervalMs);
 		this.#handle.unref?.();
@@ -143,10 +148,9 @@ export class LoopWatchdog {
 		const now = this.#now();
 		const blockedMs = now - this.#expected;
 		const cpuMs = this.#cpuNow() - this.#expectedCpu;
-		// Consume the recent phase every tick (block or not) so attribution is
-		// scoped to the just-elapsed interval and never carries a stale phase
-		// forward to a later, phase-less block.
-		const phase = takeRecentLoopPhase();
+		// Consume every valid tick, even without a warning, so no phase carries
+		// forward into a later, phase-less block.
+		const phase = takeLoopPhaseAttribution(now);
 		if (blockedMs > this.#thresholdMs) {
 			if (this.#isSuspension(blockedMs, cpuMs)) {
 				this.#wasBlocked = false;
@@ -157,7 +161,8 @@ export class LoopWatchdog {
 					logger.warn("ui.loop-blocked", {
 						blockedMs: Math.round(blockedMs),
 						cpuMs: Math.round(cpuMs),
-						phase: phase ?? "unknown",
+						phase: phase?.label ?? "unknown",
+						...(phase ? { phaseMs: Math.round(phase.ms) } : {}),
 					});
 				}
 			}

package/src/multiplexers/cmux.d.ts

@@ -0,0 +1,16 @@
+export declare const cmuxMultiplexer: {
+    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;
+    /**
+     * Workspace/socket state alone is not enough: only the injected surface UUID
+     * identifies the pane that should receive the notification. Without a valid
+     * surface, or without the binary, delivery falls through unchanged.
+     */
+    readonly notifier: {
+        readonly tier: "surface";
+        readonly send: ({ message, env }: import("./types").TerminalMultiplexerNotificationRequest) => boolean;
+    };
+};

package/src/multiplexers/cmux.ts

@@ -0,0 +1,29 @@
+import { notificationTitleAndBody, spawnNotifier } from "./notify";
+import type { TerminalMultiplexerModule } from "./types";
+
+const CMUX_SURFACE_ID_PATTERN = /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/iu;
+
+export const cmuxMultiplexer = {
+	id: "cmux",
+	precedence: "session",
+	// CMUX_SOCKET_PATH is a CLI socket override and can be set outside a CMUX terminal.
+	sessionEnvKeys: ["CMUX_WORKSPACE_ID", "CMUX_SURFACE_ID", "CMUX_REMOTE_TRANSPORT"],
+	ownsScreenGrid: true,
+	isInside(env: NodeJS.ProcessEnv = Bun.env): boolean {
+		return Boolean(env.CMUX_WORKSPACE_ID || env.CMUX_SURFACE_ID || env.CMUX_REMOTE_TRANSPORT);
+	},
+	/**
+	 * Workspace/socket state alone is not enough: only the injected surface UUID
+	 * identifies the pane that should receive the notification. Without a valid
+	 * surface, or without the binary, delivery falls through unchanged.
+	 */
+	notifier: {
+		tier: "surface",
+		send({ message, env }) {
+			const surfaceId = env.CMUX_SURFACE_ID?.trim();
+			if (!surfaceId || !CMUX_SURFACE_ID_PATTERN.test(surfaceId)) return false;
+			const { title, body } = notificationTitleAndBody(message);
+			return spawnNotifier(["cmux", "notify", "--surface", surfaceId, "--title", title, "--body", body]);
+		},
+	},
+} as const satisfies TerminalMultiplexerModule;

package/src/multiplexers/herdr.d.ts

@@ -0,0 +1,26 @@
+export declare const herdrMultiplexer: {
+    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;
+    /**
+     * 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 its CLI 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. The exact pane ID addresses the CLI call; without a valid one, or
+     * without the binary, delivery falls through.
+     */
+    readonly notifier: {
+        readonly tier: "pane";
+        readonly send: ({ message, env }: import("./types").TerminalMultiplexerNotificationRequest) => boolean;
+    };
+    readonly hyperlinks: "render";
+    readonly honorsSynchronizedOutput: true;
+    readonly imagesRequireOverride: true;
+};

package/src/multiplexers/herdr.ts

@@ -0,0 +1,64 @@
+import { DEFAULT_NOTIFICATION_TITLE, notificationTitleAndBody, spawnNotifier } from "./notify";
+import type { TerminalMultiplexerModule } from "./types";
+
+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: Record<string, true> = { help: true, "--help": true, "-h": true };
+
+export const herdrMultiplexer = {
+	id: "herdr",
+	precedence: "session",
+	sessionEnvKeys: ["HERDR_ENV", "HERDR_PANE_ID", "HERDR_TAB_ID", "HERDR_WORKSPACE_ID"],
+	ownsScreenGrid: true,
+	isInside(env: NodeJS.ProcessEnv = Bun.env): boolean {
+		// Identity vars survive env-sanitizing launchers that drop HERDR_ENV.
+		// Client-only socket, binary, session, and config overrides are not proof
+		// that this process runs inside a pane.
+		return env.HERDR_ENV === "1" || Boolean(env.HERDR_PANE_ID || env.HERDR_TAB_ID || env.HERDR_WORKSPACE_ID);
+	},
+	/**
+	 * 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 its CLI 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. The exact pane ID addresses the CLI call; without a valid one, or
+	 * without the binary, delivery falls through.
+	 */
+	notifier: {
+		tier: "pane",
+		send({ message, env }) {
+			const paneId = env.HERDR_PANE_ID?.trim();
+			if (!paneId || !HERDR_PANE_ID_PATTERN.test(paneId)) return false;
+
+			const parsed = notificationTitleAndBody(message);
+			const title = Object.hasOwn(HERDR_USAGE_TOKENS, parsed.title) ? DEFAULT_NOTIFICATION_TITLE : parsed.title;
+			const kinds = typeof message === "string" ? [] : [message.type ?? []].flat();
+			const sound =
+				kinds.includes("ask") || kinds.includes("error")
+					? "request"
+					: kinds.includes("completion")
+						? "done"
+						: "none";
+			return spawnNotifier(["herdr", "notification", "show", title, "--body", parsed.body, "--sound", sound]);
+		},
+	},
+	// Herdr hides the outer terminal (`TERM=xterm-256color`, no `TERM_PROGRAM`),
+	// but renders OSC 8 in its own grid and opens links itself on Ctrl+click.
+	hyperlinks: "render",
+	// The pane VTE is libghostty and suppresses compositing while DEC 2026 is
+	// set. Without sync, CUP-diff paints and split write(2) chunks composite as
+	// dirty-row patches: the live viewport tears, its top frozen while only the
+	// bottom refreshes.
+	honorsSynchronizedOutput: true,
+	// The pane marker does not prove the client enabled Herdr's experimental
+	// Kitty renderer, and leaked outer-terminal identities cannot either.
+	imagesRequireOverride: true,
+} as const satisfies TerminalMultiplexerModule;

package/src/multiplexers/notify.d.ts

@@ -0,0 +1,13 @@
+import type { TerminalNotification } from "../terminal-capabilities";
+/** Title for out-of-band multiplexer notifications that carry none of their own. */
+export declare const DEFAULT_NOTIFICATION_TITLE = "omp";
+/** Title and body for an out-of-band multiplexer notification (cmux, Herdr). */
+export declare function notificationTitleAndBody(message: string | TerminalNotification): {
+    title: string;
+    body: string;
+};
+/**
+ * Start a notifier CLI without waiting for or pinning it. Returns false when
+ * the binary cannot be spawned, which leaves delivery to the terminal fallback.
+ */
+export declare function spawnNotifier(cmd: string[]): boolean;

package/src/multiplexers/notify.ts

@@ -0,0 +1,24 @@
+import type { TerminalNotification } from "../terminal-capabilities";
+
+/** Title for out-of-band multiplexer notifications that carry none of their own. */
+export const DEFAULT_NOTIFICATION_TITLE = "omp";
+
+/** Title and body for an out-of-band multiplexer notification (cmux, Herdr). */
+export function notificationTitleAndBody(message: string | TerminalNotification): { title: string; body: string } {
+	if (typeof message === "string") return { title: DEFAULT_NOTIFICATION_TITLE, body: message };
+	return { title: message.title?.trim() || DEFAULT_NOTIFICATION_TITLE, body: message.body ?? "" };
+}
+
+/**
+ * Start a notifier CLI without waiting for or pinning it. Returns false when
+ * the binary cannot be spawned, which leaves delivery to the terminal fallback.
+ */
+export function spawnNotifier(cmd: string[]): boolean {
+	try {
+		const child = Bun.spawn({ cmd, stdin: "ignore", stdout: "ignore", stderr: "ignore" });
+		child.unref();
+	} catch {
+		return false;
+	}
+	return true;
+}

package/src/multiplexers/orca.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Orca is an xterm.js-based IDE whose terminals expose paired pane/worktree IDs.
+ * It is recognized for launches, but it ranks below nested multiplexers and keeps
+ * the direct-terminal render path it used before it was recognized.
+ */
+export declare const orcaMultiplexer: {
+    readonly id: "orca";
+    readonly precedence: "outerApp";
+    readonly sessionEnvKeys: readonly ["ORCA_PANE_KEY", "ORCA_WORKTREE_ID"];
+    readonly ownsScreenGrid: false;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+};

package/src/multiplexers/orca.ts

@@ -0,0 +1,16 @@
+import type { TerminalMultiplexerModule } from "./types";
+
+/**
+ * Orca is an xterm.js-based IDE whose terminals expose paired pane/worktree IDs.
+ * It is recognized for launches, but it ranks below nested multiplexers and keeps
+ * the direct-terminal render path it used before it was recognized.
+ */
+export const orcaMultiplexer = {
+	id: "orca",
+	precedence: "outerApp",
+	sessionEnvKeys: ["ORCA_PANE_KEY", "ORCA_WORKTREE_ID"],
+	ownsScreenGrid: false,
+	isInside(env: NodeJS.ProcessEnv = Bun.env): boolean {
+		return Boolean(env.ORCA_PANE_KEY?.trim() && env.ORCA_WORKTREE_ID?.trim());
+	},
+} as const satisfies TerminalMultiplexerModule;

package/src/multiplexers/screen.d.ts

@@ -0,0 +1,9 @@
+export declare const screenMultiplexer: {
+    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";
+};

package/src/multiplexers/screen.ts

@@ -0,0 +1,15 @@
+import type { TerminalMultiplexerModule } from "./types";
+
+export const screenMultiplexer = {
+	id: "screen",
+	precedence: "session",
+	sessionEnvKeys: ["STY"],
+	termPrefix: "screen",
+	ownsScreenGrid: true,
+	isInside(env: NodeJS.ProcessEnv = Bun.env): boolean {
+		return Boolean(env.STY);
+	},
+	// GNU screen never gained OSC 8 support, so a screen layer anywhere in the
+	// path vetoes hyperlinks, even under a nested tmux.
+	hyperlinks: "drop",
+} as const satisfies TerminalMultiplexerModule;

package/src/multiplexers/tmux.d.ts

@@ -0,0 +1,29 @@
+/** Wrap a control sequence in tmux's DCS passthrough envelope. */
+export declare function wrapTmuxPassthrough(payload: string): string;
+export declare const tmuxMultiplexer: {
+    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 }: import("./types").TerminalMultiplexerNotificationRequest) => boolean;
+    };
+    readonly hyperlinks: {
+        readonly forward: {
+            readonly termProgram: "tmux";
+            readonly major: 3;
+            readonly minor: 4;
+        };
+    };
+    readonly backgroundColorCache: {
+        readonly passthrough: typeof wrapTmuxPassthrough;
+        readonly settleMs: 100;
+    };
+    readonly expandsRepPadding: true;
+    readonly expiresSynchronizedOutput: true;
+    readonly altRestoreEndsSynchronizedOutput: true;
+    readonly growsBeforeSigwinch: true;
+};

package/src/multiplexers/tmux.ts

@@ -0,0 +1,40 @@
+import type { TerminalMultiplexerModule } from "./types";
+
+/** Wrap a control sequence in tmux's DCS passthrough envelope. */
+export function wrapTmuxPassthrough(payload: string): string {
+	return `\x1bPtmux;${payload.replaceAll("\x1b", "\x1b\x1b")}\x1b\\`;
+}
+
+export const tmuxMultiplexer = {
+	id: "tmux",
+	precedence: "session",
+	sessionEnvKeys: ["TMUX"],
+	termPrefix: "tmux",
+	ownsScreenGrid: true,
+	isInside(env: NodeJS.ProcessEnv = Bun.env): boolean {
+		return Boolean(env.TMUX);
+	},
+	notifier: {
+		tier: "inBand",
+		// tmux swallows bare OSCs; passthrough preserves the toast and BEL flags
+		// the pane. Bell notifications already provide that signal. One write
+		// keeps a concurrent renderer from interleaving between the two.
+		send({ sequence, write }) {
+			if (sequence === null) return false;
+			write(`${wrapTmuxPassthrough(sequence)}\x07`);
+			return true;
+		},
+	},
+	// tmux 3.4 stores OSC 8 as a cell attribute and forwards it to outer
+	// terminals whose `terminal-features` include `hyperlinks`; it self-reports
+	// via TERM_PROGRAM/TERM_PROGRAM_VERSION since 3.2a.
+	hyperlinks: { forward: { termProgram: "tmux", major: 3, minor: 4 } },
+	// An explicit appearance refresh passes OSC 11 to the outer terminal, then
+	// re-reads tmux's cache once it has consumed the reply.
+	backgroundColorCache: { passthrough: wrapTmuxPassthrough, settleMs: 100 },
+	expandsRepPadding: true,
+	// tmux expires synchronized output after one second.
+	expiresSynchronizedOutput: true,
+	altRestoreEndsSynchronizedOutput: true,
+	growsBeforeSigwinch: true,
+} as const satisfies TerminalMultiplexerModule;

package/src/multiplexers/types.d.ts

@@ -0,0 +1,100 @@
+import type { TerminalNotification } from "../terminal-capabilities";
+/**
+ * Classification tier. `session` markers outrank the TERM fallback; `outerApp`
+ * hosts rank below it so a multiplexer nested inside them still wins.
+ */
+export type TerminalMultiplexerPrecedence = "session" | "outerApp";
+/**
+ * Notification delivery tier, tried in this order so the innermost target wins:
+ * a `pane` notifier addresses the exact pane through the multiplexer's CLI, a
+ * `surface` notifier addresses the containing app surface, and an `inBand`
+ * notifier rewrites the terminal's own notification sequence.
+ */
+export type TerminalMultiplexerNotificationTier = "pane" | "surface" | "inBand";
+/** One notification offered to a multiplexer notifier. */
+export interface TerminalMultiplexerNotificationRequest {
+    readonly message: string | TerminalNotification;
+    readonly env: NodeJS.ProcessEnv;
+    /** The host terminal's formatted OSC notification, or `null` when it notifies with a bare BEL. */
+    readonly sequence: string | null;
+    /** Write a sequence through the active terminal. */
+    write(data: string): void;
+}
+export interface TerminalMultiplexerNotifier {
+    readonly tier: TerminalMultiplexerNotificationTier;
+    /** Deliver the notification. `false` leaves it to the next notifier and then the terminal fallback. */
+    send(request: TerminalMultiplexerNotificationRequest): boolean;
+}
+/**
+ * OSC 8 handling inside a multiplexer session:
+ * - `render`: the multiplexer draws and opens links itself, so links work
+ *   whatever the outer terminal supports, unless another session with a
+ *   hyperlink policy sits in the path.
+ * - `drop`: never forwards OSC 8; its session anywhere in the path disables links.
+ * - `forward`: forwards OSC 8 once it self-reports (`TERM_PROGRAM`/`TERM_PROGRAM_VERSION`)
+ *   at least `major.minor`; older or unreported versions stay off.
+ */
+export type TerminalMultiplexerHyperlinks = "render" | "drop" | {
+    readonly forward: {
+        /** Lowercase `TERM_PROGRAM` the multiplexer sets inside its panes. */
+        readonly termProgram: string;
+        readonly major: number;
+        readonly minor: number;
+    };
+};
+/** A multiplexer that answers OSC 11 from a cached copy of the outer terminal's background color. */
+export interface TerminalMultiplexerBackgroundColorCache {
+    /** Wrap a query so it reaches the outer terminal and refreshes the cache. */
+    passthrough(query: string): string;
+    /** How long the multiplexer needs to store the outer reply before the cache is re-read. */
+    readonly settleMs: number;
+}
+/** Everything omp needs to recognize one terminal multiplexer and adapt to it. */
+export interface TerminalMultiplexerModule<Id extends string = string> {
+    readonly id: Id;
+    readonly precedence: TerminalMultiplexerPrecedence;
+    /** Every environment variable `isInside()` reads. */
+    readonly sessionEnvKeys: readonly string[];
+    /** Lowercase TERM prefix that identifies the multiplexer when its session markers were stripped. */
+    readonly termPrefix?: string;
+    /**
+     * Whether the multiplexer owns the screen grid. When true, rendering takes the
+     * multiplexer path (no scrollback rebuild, anchored resize, skipped probes).
+     */
+    readonly ownsScreenGrid: boolean;
+    isInside(env?: NodeJS.ProcessEnv): boolean;
+    /** Routes notifications the multiplexer would otherwise swallow. */
+    readonly notifier?: TerminalMultiplexerNotifier;
+    /** OSC 8 policy inside a session; unset defers to the outer terminal. */
+    readonly hyperlinks?: TerminalMultiplexerHyperlinks;
+    /**
+     * The pane's VTE honors DEC 2026 even when DECRQM is unanswered or reports
+     * the mode unrecognized (status 0): synchronized output starts on inside a
+     * session, and an unrecognized report does not turn it off.
+     */
+    readonly honorsSynchronizedOutput?: boolean;
+    /**
+     * The session does not reveal whether its client renders graphics while
+     * outer-terminal identity variables leak in, so images and Kitty
+     * placeholders stay off unless the user forces them.
+     */
+    readonly imagesRequireOverride?: boolean;
+    /** Platforms where the multiplexer breaks OSC 11 passthrough, so host appearance is used instead. */
+    readonly backgroundQueryBrokenOn?: readonly NodeJS.Platform[];
+    /** Present when OSC 11 replies come from a cache an explicit refresh must update first. */
+    readonly backgroundColorCache?: TerminalMultiplexerBackgroundColorCache;
+    /** Expands REP into identical styled cells, so destructive replays REP-encode their padding. */
+    readonly expandsRepPadding?: boolean;
+    /** Expires a synchronized update after a deadline, so large rebuild replays renew DEC 2026 as they stream. */
+    readonly expiresSynchronizedOutput?: boolean;
+    /**
+     * Restoring the alternate buffer schedules a redraw that ends a synchronized
+     * update early, so a synchronized resize rebuild stays on the main buffer.
+     */
+    readonly altRestoreEndsSynchronizedOutput?: boolean;
+    /**
+     * May grow its grid before SIGWINCH reaches the app, so a rebuild-mode grow
+     * whose full viewport no longer reaches the bottom replays history.
+     */
+    readonly growsBeforeSigwinch?: boolean;
+}