Expose pane terminal modes to direct TerminalAttach clients

[KaminariOS]

Problem

Direct TerminalAttach clients receive rendered pane frames but not the pane application’s terminal-mode state.

Herdr parses the child PTY output into its terminal runtime and sends rendered cell differences. The original DECSET transitions therefore do not reach the attaching client’s terminal emulator.

A client cannot determine whether the pane application has enabled:

• alternate screen (47, 1047, or 1049)
• mouse tracking (1000, 1002, or 1003)
• mouse encoding (1006, 1015, or 1016)

The existing MouseCapture message represents Herdr’s outer UI capture behavior, not the attached pane application’s requested mouse protocol.

Why this matters

A graphical client such as an Android Herdr client needs to distinguish:

1. A shell or cat -v, which requested no mouse input.
2. A mouse-aware TUI such as Yazi, which requested SGR mouse reporting.

If the client forwards every tap, ordinary programs receive unexpected input such as:

^[[<0;44;40M^[[<0;44;40m

If the client forwards taps only when its terminal emulator reports mouse tracking, TUI taps do not work—the emulator never receives the mode transitions Herdr consumed.

Rendered screen contents, Ratatui usage, and alternate-screen appearance are not reliable substitutes for the actual terminal state.

Proposed protocol behavior

Send each TerminalAttach client an initial pane-mode snapshot when it attaches, followed by ordered updates whenever the state changes.

The state could include:

screen:
  primary | alternate

mouse_tracking:
  none | click | button_event | any_event

mouse_encoding:
  default | utf8 | sgr | urxvt | sgr_pixels

The exact wire representation is flexible. The important properties are:

• State is specific to the attached pane.
• A complete snapshot is sent on attach and reconnect.
• Updates remain ordered relative to rendered terminal frames.
• The values describe modes requested by the pane application, not Herdr’s outer UI settings.

Alternatively, the rendered stream could preserve the relevant DECSET transitions so the attaching terminal emulator observes them naturally.

Client behavior enabled by this

A client could mirror the reported modes into its terminal emulator and dispatch native mouse events only while the pane application has requested them.

The terminal emulator would remain responsible for encoding input according to the requested protocol. Clients would not need to construct SGR sequences or guess whether a TUI is active.

This produces safe behavior:

• cat -v or a shell: taps send no PTY input.
• Yazi or another mouse-aware TUI: taps are encoded and delivered correctly.
• Mode changes while an application starts or exits take effect immediately.
• Attaching after the TUI started works because the client receives an initial snapshot.

Scope

This proposal does not require Herdr to synthesize click sequences or change its own TUI mouse handling.

It only exposes pane terminal state already tracked by Herdr’s terminal runtime so direct-attach clients can make correct input-routing decisions.

Related reports

• Clicks do not reach a mouse-reporting pane app in herdr agent attach #3105 — clicks do not reach a mouse-reporting pane app in direct attach
• Alternate scroll (?1007) stays enabled after the pane app disables it — wheel becomes prompt-history navigation, survives restarting the agent #2943 — alternate-scroll state can remain enabled
• Wheel in terminal attach types arrow keys into the pane instead of scrolling #2993 — terminal-attach wheel input
• Alt-screen TUI panes have no real scrollback — request tmux's alternate-screen off equivalent #1304 — alternate-screen behavior and scrollback