@linxiraos/pi-tui 1.1.27 → 1.2.0

package/dist/types/overlays/session-selector.d.ts

@@ -71,7 +71,7 @@ declare class SessionList<T extends SessionSelectorEntry> implements Component {
     onExit: () => void;
     onToggleScope?: () => void;
     onDeleteRequest?: (session: T) => void;
-    /** Re-render hook for async list updates (fuzzy scan chunks, history merge). */
+    /** Re-render hook for async list updates (fuzzy scan completion, history merge). */
     onRequestRender?: () => void;
     constructor(sessions: T[], showCwd?: boolean, historyMatcher?: SessionHistoryMatcher, getTerminalRows?: () => number, pinnedIds?: ReadonlySet<string>, currentSessionPath?: string | (() => string | undefined));
     /** Replace the visible dataset, e.g. when toggling folder/all-projects scope. */
@@ -129,7 +129,11 @@ export interface SessionSelectorOptions<T extends SessionSelectorEntry = Session
     title?: string;
     /** Fixed scope label, or false to omit the scope suffix. */
     scopeLabel?: string | false;
-    /** Show each session's working directory in the list. */
+    /**
+     * Show each session's working directory in the list. Defaults to on when
+     * the session files live in more than one directory (e.g. the folder scope
+     * merging a repository's worktrees).
+     */
     showCwd?: boolean;
     /**
      * Reads the live terminal height so the visible window fits the viewport.

package/dist/types/overlays/settings-defs.d.ts

@@ -43,6 +43,7 @@ export type AnyUiMetadata = UiBase & {
     options?: ReadonlyArray<SubmenuOption> | "runtime";
     secret?: boolean;
     ordered?: boolean;
+    editor?: "json";
 };
 /** Structural schema entries supplied by the application host. */
 export interface SettingsDisplayEntry {

package/dist/types/overlays/usage-dashboard.d.ts

@@ -33,10 +33,12 @@ export interface ProviderCard {
     /** Number of represented accounts, including unavailable usage lookups. */
     accounts: number;
     unavailableAccounts: string[];
-    /** Window rows sorted most-pressing first. */
+    /** Window rows in provider-declared order (e.g. 5h → weekly → monthly); the fullest CARD_MAX_WINDOWS lead. */
     windows: CardWindowRow[];
-    /** True when every account reports no limits (e.g. enterprise plans). */
+    /** True when every account reports no limits (e.g. enterprise plans, providers without a quota API). */
     unlimited: boolean;
+    /** Distinct report notes across accounts (e.g. why a provider exposes no quota windows). */
+    notes: string[];
     /** True when nothing is used anywhere (or there are no limits): collapses to a tick. */
     idle: boolean;
     resetCredits?: {
@@ -52,8 +54,10 @@ export interface ProviderCard {
  * Collapse usage reports into one compact card per provider: limits grouped by
  * quota bucket (label + window), each bucket showing the mean used fraction
  * across accounts (matching the classic report's aggregate "% free") with the
- * most-used account's reset countdown. Cards sort most-pressing first so
- * what's burning is on top-left; fully idle providers collapse into a tick.
+ * most-used account's reset countdown. Rows keep the provider's declared window
+ * order so 5h → week → month reads the same every time; cards sort by their
+ * fullest window so what's burning is on top-left; fully idle providers
+ * collapse into a tick.
  */
 export declare function buildProviderCards(reports: UsageReport[], nowMs: number, unavailableAccounts?: readonly UnavailableUsageAccount[]): ProviderCard[];
 /** GitHub-style week-per-column heatmap grid derived from daily activity. */

package/dist/types/overlays/usage-display.d.ts

@@ -1,4 +1,4 @@
-import type { UsageLimit, UsageReport, UsageResetCredits } from "@linxiraos/pi-ai";
+import type { UsageLimit, UsageReport, UsageResetCreditDetail, UsageResetCredits } from "@linxiraos/pi-ai";
 /** Include the usage tier in a limit title unless its label already names it. */
 export declare function formatLimitTitle(limit: UsageLimit): string;
 /** Human-readable quota scope for a normalized saved-reset window ID. */
@@ -10,6 +10,8 @@ export interface UsageResetSummary {
     soonestExpiry?: string;
     unavailableReason?: string;
 }
+/** Expiry (epoch ms) of a credit that still banks a reset, whether or not it can be spent now. */
+export declare function bankedResetCreditExpiryMs(credit: UsageResetCreditDetail): number | undefined;
 /**
  * Normalize old count-only and current provider reset metadata for display.
  * `availableCount` is banked inventory; `redeemableCount` is the subset that

package/dist/types/prompt/composer.d.ts

@@ -47,7 +47,7 @@ export interface ComposerStatusCache {
 /** Optional dependencies and initial state for a standalone composer. */
 export interface ComposerOptions {
     readonly terminal?: Terminal;
-    /** Extra TUI construction options (render scheduler injection for tests and `zeta render`). */
+    /** Extra TUI construction options (render scheduler injection for tests and `zetacode render`). */
     readonly tuiOptions?: TUIOptions;
     readonly preferences?: Partial<ComposerPreferences>;
     readonly welcome?: ComposerWelcomeUpdate;

package/dist/types/prompt/custom-editor.d.ts

@@ -7,7 +7,7 @@ import type { AppKeybinding } from "../app-keybindings.js";
 import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 import type { ComposerFactsSource } from "../status-line/types.js";
 import { type MacOSSpellingFeatures } from "./macos-spelling.js";
-import type { TspEditorDecoration } from "@linxiraos/pi-wire";
+import type { TspEditorDecoration, TspText } from "@linxiraos/pi-wire";
 import { type WordCompletionMethod } from "./word-completion.js";
 /** Live composer state the TSP layout shows; the interactive host wires {@link CustomEditor.composerState}. */
 export interface ComposerNativeState {
@@ -26,6 +26,8 @@ export interface ComposerNativeState {
     readonly running: boolean;
     /** The viewed subagent's lineage, outermost first and the viewed agent last; undefined on the main session. */
     readonly viewing?: readonly string[];
+    /** The session's title, quoted in italics as the TSP placeholder; undefined until it has one. */
+    readonly title?: string;
 }
 /** Independently switchable prose-assistance features of the composer. */
 export interface SpellingFeatures extends MacOSSpellingFeatures {
@@ -116,19 +118,19 @@ export declare class CustomEditor extends Editor {
      *  Numbered by a per-draft monotonic counter so a deleted chip never recycles its number
      *  (labels key the atom table). */
     pendingTexts: TextAttachment[];
-    /** Host-wired producer of per-image `file://` links (session blob store); drives clickable
-     *  chip tokens for restored drafts (esc-esc, `/tree`, branch). */
+    /** Host-wired producer of per-image chip targets (a file on disk, or a session blob copy);
+     *  drives clickable chip tokens for restored drafts (esc-esc, `/tree`, branch). */
     draftImageLinkMaterializer?: (images: readonly ImageContent[]) => Promise<(string | undefined)[] | undefined>;
     /**
      * The host {@link TUI}, captured when a plugin constructs this editor through
-     * the upstream-pi `(tui, theme, keybindings)` convention. Undefined for zeta's
+     * the upstream-pi `(tui, theme, keybindings)` convention. Undefined for omp's
      * own `new CustomEditor(theme)` callers (they drive repaints through the
      * interactive-mode wiring instead). Plugins that call `this.tui.requestRender()`
      * in their overrides read it here (issue #4766).
      */
     tui?: TUI;
     /**
-     * Accept both the zeta constructor convention — `new CustomEditor(theme)` —
+     * Accept both the omp constructor convention — `new CustomEditor(theme)` —
      * and the upstream-pi `Editor` convention — `new Editor(tui, theme, keybindings)`
      * — that {@link ExtensionUIContext.setEditorComponent}'s factory contract
      * advertises `(tui, theme, keybindings)`. Plugins written against upstream pi
@@ -191,7 +193,8 @@ export declare class CustomEditor extends Editor {
     static readonly SHIMMER_PERIOD_MS = 1800;
     /** Decorate magic keywords, attachments, and the queue-composer header/list markers.
      *  Queue shorthand reserves its first logical line as a dim `Queueing` label; sequential
-     *  item markers use the accent color so separate follow-ups remain visible while composing. */
+     *  item markers use the accent color so separate follow-ups remain visible while composing.
+     *  Called once per layout segment, so whole-buffer inputs are computed once per text revision. */
     decorateText: (text: string, context: EditorTextDecorationContext) => string;
     /**
      * TSP decorations: magic keywords shimmer (terminal-clocked) in the accent
@@ -219,8 +222,8 @@ export declare class CustomEditor extends Editor {
     setShimmerRepaintHandler(handler: (() => void) | undefined): void;
     /** Editing is available during bootstrap; atomic sends wait until submission is wired and enabled. */
     protected get nativeSendable(): boolean;
-    /** Viewing a subagent, the draft goes to it: the placeholder names it. */
-    describePlaceholder: () => string;
+    /** Viewing a subagent, the draft goes to it: the placeholder names it; else the session's title, quoted in italics. */
+    describePlaceholder: () => TspText;
     /** A shell-mode draft highlights as its language. */
     describeLanguage: () => string | undefined;
     /** Host-owned live state for the TSP composer (shell mode, effort chip, send/stop). */

package/dist/types/prompt/image-source.d.ts

@@ -4,7 +4,8 @@
  * to the session's `local://` root, and generated video contact-sheet previews.
  * Symbol metadata stays out of serialized/model-bound image data while traveling
  * with the draft object, until AgentSession creates the hidden companion message
- * that tells the model the path (and link materialization prefers it over a blob copy).
+ * that tells the model the path. The model keeps `local://` references across
+ * `/move`; chips for internal URLs instead use a stable blob copy.
  */
 import type { ImageContent } from "@linxiraos/pi-ai";
 /** How an image attachment's backing file entered the session. */

package/dist/types/prompt/interactive-context-helpers.d.ts

@@ -17,13 +17,16 @@ export interface AssistantMessageHost {
     readonly proseOnlyThinking: boolean;
     readonly expandThinkingBlocks: boolean;
     readonly assistantImagesVisible: boolean;
+    /** Whether the viewed session's tables get charts: the main session's do, a focused subagent's do not. */
+    readonly tableChartsVisible: boolean;
     readonly hideToolActivity: boolean;
     readonly toolOutputExpanded: boolean;
     readonly ui: {
         requestRender(): void;
         readonly imageBudget: ImageBudget;
     };
-    resolveAssistantMessageLinks(texts: readonly string[]): Promise<ReadonlyMap<string, string>>;
+    /** Resolve already-extracted Markdown link destinations to local targets. */
+    resolveAssistantMessageLinkHrefs(hrefs: readonly string[]): Promise<ReadonlyMap<string, string>>;
 }
 /**
  * Resolve and cache the current session's model-authored prose links. Existing

package/dist/types/prompt/model-mention-autocomplete.d.ts

@@ -19,7 +19,7 @@ export declare function applyModelMentionCompletion(lines: string[], cursorLine:
 };
 /**
  * Create a session-scoped model candidate lookup using picker ordering. The
- * scope and search affinity are reused across queries until their inputs change.
+ * scope and its prepared ranker are reused across queries until their inputs change.
  */
 export declare function createModelMentionSource(host: {
     source: ModelBrowserSource;

package/dist/types/prompt/welcome.d.ts

@@ -14,7 +14,12 @@ export declare const WELCOME_LSP_SLOTS = 4;
  *  `r` is a uniform sample in [0, 1). Returns "" when `tips` is empty.
  *  Exported for tests. */
 export declare function pickWeightedTip(tips: readonly string[], r: number): string;
-export declare function renderWelcomeTip(tip: string, boxWidth: number, phase?: number): string[];
+/**
+ * The welcome tip as lines of at most `width` columns: `Tip:` and the body
+ * wrapped together, with no indent, so the banner can center each line.
+ * `[]` when `width` leaves no room for a useful line.
+ */
+export declare function renderWelcomeTip(tip: string, width: number, phase?: number): string[];
 export interface RecentSession {
     name: string;
     timeAgo: string;

package/dist/types/render/composite.d.ts

@@ -0,0 +1,2 @@
+/** Splice overlay content into a base line at a specific column. Single-pass optimized. */
+export declare function compositeLineAt(baseLine: string, overlayLine: string, startCol: number, overlayWidth: number, totalWidth: number): string;

package/dist/types/render/output-pane.d.ts

@@ -92,6 +92,7 @@ export declare class OutputPane implements Component {
     describe(_cx: DescribeContext): NativeNode;
     render(width: number): readonly string[];
     invalidate(): void;
+    releaseRenderCaches(): void;
 }
 /** Default styling for plain tool output while preserving existing ANSI. */
 export declare function styleToolOutputLine(line: string, theme: Theme): string;

package/dist/types/render/render-utils.d.ts

@@ -298,6 +298,7 @@ export interface RenderedStringCache {
 export declare function createRenderedStringCache(): RenderedStringCache;
 /** Drop the memo so the next lookup re-renders (e.g. the render function identity changed). */
 export declare function invalidateRenderedStringCache(cache: RenderedStringCache): void;
+export declare function releaseRenderedStringCache(cache: RenderedStringCache): void;
 /** Reuse a rendered string while its theme, expansion, content, and salt match. */
 export declare function cachedRenderedString(cache: RenderedStringCache | undefined, theme: Theme, expanded: boolean, salt: string, content: string, render: () => string): string;
 /**

package/dist/types/render/tool-card.d.ts

@@ -46,6 +46,11 @@ export interface ToolCardOptions {
     paddingY?: number;
     ignoreTight?: boolean;
     onInvalidate?: () => void;
+    /**
+     * Drop builder-owned memos the next build recomputes. Called by
+     * {@link ToolCard.releaseRenderCaches}, which never calls `onInvalidate`.
+     */
+    onReleaseRenderCaches?: () => void;
     onDispose?: () => void;
 }
 /** Map transcript lifecycle terminology onto the output frame's visual states. */
@@ -71,6 +76,7 @@ export declare class ToolCard implements Component {
     handleInput(data: string): void;
     setIgnoreTight(ignore: boolean): void;
     invalidate(): void;
+    releaseRenderCaches(): void;
     dispose(): void;
 }
 /** Construct a lazy framed tool card. */

package/dist/types/render/width-aware-text.d.ts

@@ -20,6 +20,8 @@ export declare class WidthAwareText implements Component {
     setCustomBgFn(customBgFn?: (text: string) => string): void;
     setIgnoreTight(ignore: boolean): this;
     invalidate(): void;
+    /** The formatted text stays: the inner `Text` renders from it, so dropping it would free nothing. */
+    releaseRenderCaches(): void;
     /**
      * Re-run the formatter on the next render because its inputs changed.
      * Unlike {@link invalidate}, the inner `Text` keeps its wrap cache, so a

package/dist/types/setup/scenes/types.d.ts

@@ -28,6 +28,7 @@ export interface SetupHost extends SetupUiHost {
     readonly disabledProviders: readonly string[];
     readonly authStorage: AuthStorage;
     readonly modelSource: ModelBrowserSource;
+    /** Available and catalog models of every kind; role chips resolve over all of them, rows list chat models. */
     getModels(): {
         available: Model[];
         all: Model[];

package/dist/types/status-line/component.d.ts

@@ -86,6 +86,7 @@ export declare class StatusLineComponent<TSession extends StatusLineSession = St
     setPlanModeStatus(status: {
         enabled: boolean;
         paused: boolean;
+        workflow?: "parallel" | "iterative" | "ultra";
     } | undefined): void;
     setLoopModeStatus(status: NonNullable<SegmentContext["loopMode"]> | undefined): void;
     setGoalModeStatus(status: {
@@ -113,6 +114,8 @@ export declare class StatusLineComponent<TSession extends StatusLineSession = St
     setRecording(recording: boolean): void;
     /** Set the callback that presents detected Codex reset celebrations, or clear it with `undefined`. */
     setCodexResetFireworksHandler(handler: ((event: CodexResetFireworksEvent) => void) | undefined): void;
+    /** Set the callback that presents the first pool-wide saved-reset expiry warning, or clear it with `undefined`. */
+    setResetExpiryNoticeHandler(handler: ((notice: string) => void) | undefined): void;
     setHookStatus(key: string, text: string | undefined): void;
     watchBranch(onBranchChange: () => void): void;
     dispose(): void;

package/dist/types/status-line/host.d.ts

@@ -2,7 +2,7 @@ import type { AgentMessage, ThinkingLevel } from "@linxiraos/pi-agent-core";
 import type { Tool, UsageLimit, UsageReport } from "@linxiraos/pi-ai";
 import type { Model } from "@linxiraos/pi-catalog/types";
 import type { CompactionBoundaries } from "./context-usage.js";
-import type { StatusLineSettings } from "./types.js";
+import type { StatusLineSettings, StatusResetExpiry } from "./types.js";
 export interface StatusAccountIdentity {
     accountId?: string;
     email?: string;
@@ -126,6 +126,9 @@ export interface StatusLineHost<TSession extends StatusLineSession = StatusLineS
     }>;
     calculateTokensPerSecond(messages: readonly AgentMessage[], isStreaming: boolean): number | null;
     limitMatchesActiveAccount(report: UsageReport, limit: UsageLimit, identity: StatusAccountIdentity): boolean;
+    classifyResetExpiry?(report: UsageReport, nowMs: number): StatusResetExpiry | undefined;
+    /** One-line warning for saved resets anywhere in the pool that expire within 24 hours. */
+    resetExpiryNotice?(reports: readonly UsageReport[], nowMs: number): string | undefined;
     computeCompactionBoundaries(session: TSession, contextWindow: number, model?: Model): CompactionBoundaries | null;
 }
 export interface FooterHost {

package/dist/types/status-line/segments.d.ts

@@ -7,6 +7,8 @@ export type { SegmentContext } from "./types.js";
  * model segment and the composer's effort chip.
  */
 export declare function thinkingLevelWord(session: Pick<StatusLineSession, "state" | "isAutoThinking" | "autoResolvedThinkingLevel">): string | undefined;
+/** Zeta-only: the ultra plan workflow gets its own status-line label (lost in the v18.8.8 merge once already). */
+export declare const PLAN_ULTRA_LABEL = "Plan-Ultra";
 export declare const SEGMENTS: Record<StatusLineSegmentId, StatusLineSegment>;
 export declare function renderSegment(id: StatusLineSegmentId, ctx: SegmentContext): RenderedSegment;
 /** Native description of one segment; null when it is hidden or unknown. */

package/dist/types/status-line/types.d.ts

@@ -93,6 +93,8 @@ export interface SegmentContext {
     planMode: {
         enabled: boolean;
         paused: boolean;
+        /** Plan workflow variant; `ultra` renders as `Plan-Ultra` in the mode segment. */
+        workflow?: "parallel" | "iterative" | "ultra";
     } | null;
     prewalk: {
         enabled: boolean;
@@ -112,7 +114,7 @@ export interface SegmentContext {
     } | null;
     /** Modal editing state, or null when `tui.vimMode` is off. */
     vim: {
-        mode: "insert" | "normal" | "visual" | "visual-line";
+        mode: "insert" | "normal" | "visual" | "visual-line" | "replace";
         /** Half-typed operator/count (`"2d"`), empty when nothing is pending. */
         pending: string;
         /** Lines spanned by the active Visual selection; 0 outside Visual modes. */
@@ -223,9 +225,18 @@ export interface SegmentContext {
             expiryHours?: number;
             expired?: boolean;
             unavailableReason?: string;
+            expiring?: StatusResetExpiry;
         };
     } | null;
 }
+/** How close an account's saved resets are to expiring, when it is worth a warning. */
+export interface StatusResetExpiry {
+    /** `soon`: within 7 days; `imminent`: within 24 hours. */
+    tier: "soon" | "imminent";
+    count: number;
+    /** Expiry of the reset the warning is about (epoch ms); it can be later than the soonest banked one. */
+    expiresAtMs: number;
+}
 export interface RenderedSegment {
     content: string;
     visible: boolean;
@@ -245,8 +256,8 @@ export interface SegmentView {
 }
 /**
  * The status line's facts for the native composer. A TSP terminal shows no
- * status strip: the tab title carries the session, the pane header the path
- * and branch, and the composer the rest.
+ * status strip: the tab title carries the session, the pane header the path,
+ * and the composer the rest (the git branch among its facts).
  */
 export interface ComposerFacts {
     /**

package/dist/types/terminal-capabilities.d.ts

@@ -1,6 +1,6 @@
 import type { HangulCompatibilityJamoWidth } from "./utils.js";
 export * from "./terminal-multiplexer.js";
-export { isInsideTmux, wrapTmuxPassthrough } from "./tmux.js";
+export { wrapTmuxPassthrough } from "./tmux.js";
 export declare enum ImageProtocol {
     Kitty = "\u001B_G",
     Iterm2 = "\u001B]1337;File=",
@@ -55,12 +55,6 @@ export declare class TerminalInfo {
     formatNotification(message: string | TerminalNotification): string;
     sendNotification(message: string | TerminalNotification): void;
 }
-/**
- * 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 declare function isInsideZellij(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Whether the agent process runs in an SSH session, so the terminal emulator
  * is remote and host-local input/keyboard modes cannot be assumed.
@@ -96,12 +90,12 @@ export declare function synchronizedOutputUserOverride(env?: NodeJS.ProcessEnv):
  *   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
@@ -167,31 +161,29 @@ export declare function hyperlinksUserOverride(env?: NodeJS.ProcessEnv): boolean
  * 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 declare function shouldEnableHyperlinksByDefault(env?: NodeJS.ProcessEnv, terminalId?: TerminalId): boolean;
 /**
@@ -343,7 +335,7 @@ 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 declare function parseKittyDirectPlacementLine(line: string): ParsedKittyPlacementLine | null;
@@ -383,8 +375,8 @@ export declare 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 declare function encodeKittyDeletePlacement(imageId: number, placementId: number): string;
 export declare function encodeITerm2(base64Data: string, options?: {

package/dist/types/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.js";
 /**
- * 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.js").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 {};