Add Hls to xterm-ghostty terminfo so tmux auto-detects OSC 8 hyperlink passthrough

[schickling-assistant]

Problem

Inside tmux, OSC 8 hyperlinks emitted by programs are silently dropped under
Ghostty unless the user manually opts in with
set -as terminal-features '*:hyperlinks'. Out of the box, hyperlinks that work
in a bare Ghostty pane disappear the moment the program runs inside tmux.

Root cause

tmux (≥3.4) only re-emits OSC 8 hyperlinks to the outer terminal when the client
terminal's terminfo carries the Hls extended capability. This is tmux's
hyperlinks terminal-feature, whose only capability is Hls in
tty-features.c (tty_feature_hyperlinks / tty_feature_hyperlinks_capabilities,
roughly):

/* tmux/tty-features.c (paraphrased; the cap is behind an ncurses-version #if) */
"Hls=\\E]8;%?%p1%l%tid=%p1%s%;;%p2%s\\E\\\\",

https://github.com/tmux/tmux/blob/master/tty-features.c

The xterm-ghostty terminfo ships no Hls:

$ infocmp -x xterm-ghostty | grep -i hls
$            # empty — no Hls

src/terminfo/ghostty.zig already defines plenty of modern extended caps
(Smulx, Setulc/Su, Ss/Se, Ms for OSC 52 clipboard, Sync, bracketed
paste, fullkbd, …) but not Hls. Notably it already ships Ms for OSC 52
clipboard while lacking Hls for OSC 8 hyperlinks — a clean, consistent gap.

Why it matters (incl. SSH propagation)

Ghostty already renders OSC 8 hyperlinks in a bare pane, so users reasonably
expect them to keep working inside tmux — the most common multiplexer. Today
they don't, and the fix is a single terminfo capability rather than per-user
tmux config.

It also propagates over SSH for free. Ghostty's ssh-terminfo integration
(installRemoteTerminfo in src/cli/ssh.zig) encodes the bundled terminfo —
extended caps included — and installs it on the remote host via tic -x -,
which preserves extended capabilities. So if xterm-ghostty shipped Hls, tmux
would auto-detect hyperlink passthrough both locally and on SSH'd-into hosts
with zero user configuration.

Reproduction

Core proof (portable, no helper script):

# 1. Ghostty's terminfo has no Hls:
$ infocmp -x xterm-ghostty | grep -i hls
$        # empty

# 2. tmux gates the `hyperlinks` feature on the `Hls` extended cap
#    (tty-features.c, linked above).

Empirical confirmation — three isolated tmux servers (private socket, explicit
-f config, no user config), each attached inside script(1) so the typescript
captures exactly the bytes tmux draws to the outer tty. A pane emits an OSC 8
hyperlink; we count ESC ] 8 introducers reaching the outer tty (0 = dropped,
≥1 = passed through; tmux re-emits with its own id=tmuxN, so a pass is
typically 2):

Case	terminfo	tmux config	ESC]8 in outer tty
A	stock xterm-ghostty	default	0 (dropped)
B	patched: stock + Hls	default	≥1 (passed)
C	stock xterm-ghostty	set -as terminal-features '*:hyperlinks'	≥1 (passed)

The only difference between A and B is the Hls capability — isolating the
missing cap as the root cause. Self-contained script:

#!/usr/bin/env bash
set -euo pipefail
WORK="$(mktemp -d)"; trap 'rm -rf "$WORK"' EXIT
OSC8='printf "\033]8;;https://example.com\033\\\\\\\\LINK\033]8;;\033\\\\\\\\\n"'

# Patched terminfo = stock xterm-ghostty + tmux's canonical Hls value.
mkdir -p "$WORK/ti"
{ infocmp -x xterm-ghostty | head -n2
  printf '\tHls=\\E]8;%%?%%p1%%l%%tid=%%p1%%s%%;;%%p2%%s\\E\\\\,\n'
  infocmp -x xterm-ghostty | tail -n +3; } > "$WORK/src"
tic -x -o "$WORK/ti" "$WORK/src" 2>/dev/null

run() { # <label> <extra-conf> <terminfo-dir-or-empty>
  local cap="$WORK/cap.$1" conf="$WORK/conf.$1"
  { echo 'set -g default-terminal "xterm-ghostty"'; echo 'set -g status off'
    printf '%s\n' "$2"; } > "$conf"
  local env=(env TERM=xterm-ghostty); [ -n "$3" ] && env+=(TERMINFO="$3")
  local inner="tmux -L hls-$1 -f '$conf' new-session -x 80 -y 24 '$OSC8; sleep 2'"
  if script --version >/dev/null 2>&1; then
    "${env[@]}" script -q -c "$inner" "$cap" >/dev/null 2>&1 || true   # util-linux
  else
    "${env[@]}" script -q "$cap" /bin/sh -c "$inner" >/dev/null 2>&1 || true  # BSD/macOS
  fi
  tmux -L "hls-$1" kill-server 2>/dev/null || true
  local n; n=$( { LC_ALL=C grep -a -o $'\033]8' "$cap" 2>/dev/null || true; } | wc -l | tr -d ' ')
  printf '%-46s ESC]8: %s\n' "$1" "${n:-0}"
}
run A_stock_default               ""                                          ""
run B_patched_with_Hls            ""                                          "$WORK/ti"
run C_stock_terminal-features-set "set -as terminal-features '*:hyperlinks'"  ""

Output (tmux 3.6a, Linux, util-linux script):

A_stock_default                                ESC]8: 0
B_patched_with_Hls                             ESC]8: 2
C_stock_terminal-features-set                  ESC]8: 2

Suggested fix

Add the Hls extended capability to src/terminfo/ghostty.zig, using tmux's
canonical value:

Hls=\E]8;%?%p1%l%tid=%p1%s%;;%p2%s\E\\

User-side workaround (for reference)

set -as terminal-features '*:hyperlinks'

Related

• Discussion Extending the use of XTGETTCAP for feature discovery #12835 (extending XTGETTCAP for feature discovery) touches Hls
  but is about runtime query discovery, not the static terminfo entry tmux reads
  at compile time — this is the simpler, separate fix.

Environment

• tmux 3.6a
• ncurses infocmp/tic (extended-cap aware)
• Linux (script also handles BSD/macOS script syntax)

[schickling-assistant]

Moved here from #13062 (closed/locked automatically because non-maintainers cannot file issues per CONTRIBUTING.md). Content is reproduced verbatim above.

[pluiedev]

No human in the loop. Piss off.

[pluiedev]

!denounce NHITL