Ship xterm-ghostty terminfo, advertise full capability set

Default TERM=xterm-256color hides ghostel's actual capabilities from
TUI apps that consult terminfo.  Most visibly, Claude Code only emits
DEC 2026 (synchronized output) when terminfo advertises `Sync`, so
without it M-x with large scrollback exhibits a choppy cascading
redraw — every small write triggers an unsynchronized partial repaint.

Ship the compiled `xterm-ghostty` entry under terminfo/ (both Linux
x/g/ and macOS 78/67/ hashed-dir layouts; identical bytes), set
TERM=xterm-ghostty + TERMINFO=<bundled> + TERM_PROGRAM=ghostty for
both `ghostel--start-process' and `ghostel-compile' via a shared
helper.  The bundled entry intentionally omits `Ms' so apps don't
silently dispatch to OSC 52 when `ghostel-enable-osc52' is off.

`defcustom ghostel-term' (default \"xterm-ghostty\") opts out by
flipping back to xterm-256color and dropping all related env.

Remote-host coverage via `defcustom ghostel-ssh-install-terminfo'
(default `auto', follows `ghostel-tramp-shell-integration'):

- TRAMP-launched ghostel: push compiled terminfo to a remote temp
  dir over the existing TRAMP connection (no extra round-trip);
  set TERMINFO=<remote dir> in the spawned shell's env; clean up on
  exit.

- Outbound `ssh' from a local buffer: bundled bash/zsh/fish
  integration shadows `ssh' with a function that resolves the
  target via `ssh -G', looks up
  ${XDG_CACHE_HOME:-~/.cache}/ghostel/ssh-terminfo-cache (key
  includes hash of local terminfo for auto-invalidation on
  libghostty bumps), and on miss runs one combined probe-and-install
  ssh (`infocmp | ssh ... 'tic -x -''), then exec's the user's
  real ssh with the resolved TERM.  Mkdir-as-lock serializes
  concurrent first-time calls to the same target.

  Skips install when the user passed a remote command (would clash
  with the pipe), when ssh -G can't resolve a host, or when local
  `infocmp' is missing.  Per-call escape: GHOSTEL_SSH_KEEP_TERM=1.

`M-x ghostel-ssh-clear-terminfo-cache' forces re-probe when a
remote's terminfo changes out of band.

Maintainer-only `make regen-terminfo' regenerates the compiled files
from terminfo/xterm-ghostty.terminfo and verifies cross-layout
parsing via `infocmp'.

Author: dakra

Makefile

@@ -6,7 +6,7 @@ EVIL_DIR       ?= $(XDG_CACHE_HOME)/evil
 
 ELC := ghostel.elc ghostel-debug.elc ghostel-compile.elc ghostel-eshell.elc
 
-.PHONY: all build test test-native test-all test-evil lint melpazoid byte-compile bench bench-quick clean
+.PHONY: all build test test-native test-all test-evil lint melpazoid byte-compile bench bench-quick clean regen-terminfo
 
 all: build test-all test-evil lint
 
@@ -67,7 +67,7 @@ melpazoid:
 	@if [ ! -d "$(MELPAZOID_DIR)" ]; then \
 		git clone https://github.com/riscy/melpazoid.git "$(MELPAZOID_DIR)"; \
 	fi
-	RECIPE='(ghostel :fetcher github :repo "dakra/ghostel" :files ("ghostel.el" "ghostel-debug.el" "ghostel-compile.el" "ghostel-module.*"))' \
+	RECIPE='(ghostel :fetcher github :repo "dakra/ghostel" :files ("ghostel.el" "ghostel-debug.el" "ghostel-compile.el" "ghostel-module.*" "terminfo"))' \
 		LOCAL_REPO=$(CURDIR) \
 		make -C "$(MELPAZOID_DIR)"
 
@@ -81,3 +81,22 @@ clean:
 	rm -f ghostel-module.dylib ghostel-module.so
 	rm -f $(ELC)
 	rm -rf zig-out .zig-cache
+
+# Maintainer-only: regenerate the bundled compiled terminfo from
+# `terminfo/xterm-ghostty.terminfo'.  Run after bumping libghostty
+# (the source file should be re-extracted from a fresh Ghostty install
+# via `infocmp -x xterm-ghostty') and commit the resulting binaries.
+# `tic' on macOS emits the BSD hashed-dir layout (78/, 67/); the
+# binary file format is identical to Linux ncurses, so we mirror the
+# compiled entries into the Linux layout (x/, g/) by copying.
+regen-terminfo:
+	rm -rf terminfo/x terminfo/g terminfo/78 terminfo/67
+	tic -x -o terminfo/ terminfo/xterm-ghostty.terminfo
+	@if [ -d terminfo/78 ]; then \
+		mkdir -p terminfo/x terminfo/g; \
+		cp terminfo/78/xterm-ghostty terminfo/x/xterm-ghostty; \
+		cp terminfo/67/ghostty terminfo/g/ghostty; \
+	fi
+	@TERMINFO=$(CURDIR)/terminfo infocmp xterm-ghostty >/dev/null \
+		|| (echo "ERROR: regenerated terminfo failed to round-trip"; exit 1)
+	@find terminfo -type f | sort

README.md

@@ -124,6 +124,12 @@ ghostty dependency automatically.
 Alternatively, download a **pre-built binary** via `M-x ghostel-download-module`
 (or `C-u M-x ghostel-download-module` to pick a specific release).
 
+The compiled `xterm-ghostty` terminfo entry ships pre-built in
+`terminfo/` and is identical to what `tic` would produce locally —
+no build step needed, and the file format is portable across BSD
+and ncurses systems.  Maintainers regenerate it via `make
+regen-terminfo` after bumping libghostty.
+
 ## Shell Integration
 
 Shell integration (directory tracking via OSC 7, prompt navigation via OSC 133,
@@ -211,6 +217,7 @@ history — even outside copy mode.
 ### Terminal Emulation
 - Full VT terminal emulation via libghostty-vt
 - 256-color and RGB (24-bit true color) support
+- **`TERM=xterm-ghostty` with bundled terminfo** — apps that consult terminfo for capabilities (Claude Code, neovim, tmux, modern TUIs) discover synchronized output (DEC 2026), Kitty keyboard protocol, true color, colored underlines, focus reporting, etc., and use their fast paths.  Synchronized output in particular eliminates the choppy partial-redraw effect when Claude Code repaints over a large scrollback.  OSC 52 (clipboard) is supported but intentionally not advertised in the bundled terminfo — see Clipboard below.  Override via `ghostel-term`.
 - **OSC 4 / 10 / 11 color queries** — TUI programs can query the current palette, foreground, and background colors, so tools like `duf`, `btop`, `delta`, and anything else using `termenv` auto-detect the right light/dark theme from the Emacs face colors
 - **OSC 9 / OSC 777** — desktop notifications and ConEmu progress reports (percentage shown in the mode line; see [Notifications and Progress](#notifications-and-progress))
 - Text attributes: bold, italic, faint, underline (single/double/curly/dotted/dashed with color), strikethrough, inverse
@@ -224,7 +231,7 @@ history — even outside copy mode.
 - **File path detection** — patterns like `/path/to/file.el:42` become clickable, opening the file at the given line (toggle with `ghostel-enable-file-detection`)
 
 ### Clipboard
-- **OSC 52 clipboard** — terminal programs can set the Emacs kill ring and system clipboard (opt-in via `ghostel-enable-osc52`, useful for remote SSH sessions)
+- **OSC 52 clipboard** — terminal programs can set the Emacs kill ring and system clipboard (opt-in via `ghostel-enable-osc52`, useful for remote SSH sessions).  Note: the bundled `xterm-ghostty` terminfo intentionally **does not** advertise the `Ms` capability, so apps don't auto-discover it.  This avoids silent clipboard drops when `ghostel-enable-osc52` is at its default `nil`.  If you enable OSC 52 and want apps (neovim, tmux) to auto-detect, install upstream Ghostty's terminfo on the same path or override `TERMINFO`.
 - **Bracketed paste** — yank from kill ring sends text as a bracketed paste so shells handle it correctly
 
 ### Input
@@ -313,6 +320,116 @@ test "$INSIDE_EMACS" = 'ghostel'; and source ~/.local/share/ghostel/ghostel.fish
 The integration scripts provide directory tracking (OSC 7), prompt
 navigation (OSC 133), and `ghostel_cmd` for calling Elisp from the shell.
 
+#### Remote `xterm-ghostty` terminfo
+
+Ghostel sets `TERM=xterm-ghostty` so apps inside the buffer get the
+full capability set (synchronized output, Kitty keyboard, etc.).
+That same `TERM` value gets inherited by anything spawned inside
+the buffer — including `ssh REMOTE` and `M-x ghostel` from a TRAMP
+`default-directory`.  Remote hosts without the `xterm-ghostty`
+entry will then print `Error opening terminal: xterm-ghostty`.
+
+`ghostel-ssh-install-terminfo` (default `auto`) handles both cases.
+`auto` is enabled when `ghostel-tramp-shell-integration` is on, so
+turning on remote integration also turns on terminfo install — one
+switch.
+
+##### TRAMP-launched ghostel
+
+`M-x ghostel` from a TRAMP path (`/ssh:host:/path/`) spawns the
+shell on the remote.  Ghostel pushes the bundled compiled terminfo
+to a remote temp dir over the existing TRAMP connection (no extra
+ssh round-trip), sets `TERMINFO=<that dir>` in the remote shell's
+env, and cleans up on exit.  Both Linux (`x/`, `g/`) and macOS
+(`78/`, `67/`) layouts are written so any ncurses or BSD libcurses
+finds it.  Nothing persists on the remote.
+
+##### Outbound `ssh` from a local ghostel buffer
+
+The bundled bash/zsh/fish integration shadows `ssh` with a function
+that:
+
+1. Resolves the canonical target via `ssh -G` (normalises ssh_config
+   aliases).
+2. Looks up the target in `~/.cache/ghostel/ssh-terminfo-cache`.
+   The cache key includes a hash of the local terminfo, so libghostty
+   bumps automatically invalidate it.  Cache hit → connect with the
+   remembered `TERM`.
+3. On miss, runs a single setup ssh that probes whether the entry
+   already exists on the remote, and if not, installs it via
+   `tic -x -` into `~/.terminfo/`.  Records `ok` (use
+   `xterm-ghostty`) or `skip` (use `xterm-256color`) in the cache.
+4. Runs the user's actual ssh with the resolved `TERM`.
+
+The setup ssh is one extra connection per new host.  Without
+ControlMaster you'll see two auth prompts the first time.  Strongly
+recommended:
+
+```ssh-config
+# ~/.ssh/config
+Host *
+    ControlMaster auto
+    ControlPath   ~/.ssh/cm-%r@%h:%p
+    ControlPersist 60s
+```
+
+With this, the setup connection and the real connection share a
+single auth.  Subsequent connections within `ControlPersist` are
+free.
+
+The cache key includes a hash of the **local** terminfo, so
+libghostty bumps automatically invalidate the cache.  It does NOT
+notice when a remote's terminfo changes out-of-band (system update,
+manual `tic`).  Run `M-x ghostel-ssh-clear-terminfo-cache` to force
+re-probe.
+
+Verified working from macOS to Linux remotes.  Mixed macOS-to-macOS
+or BSD targets inherit `tic`'s native hashed-dir layout
+(`~/.terminfo/<hex>/`); `infocmp` reads the same path so they pair
+correctly.
+
+Skip-install heuristics:
+- `ssh HOST cmd` (user passes a remote command): wrapper skips
+  install for that call to avoid clashing with the user's command.
+  Connects with cached `TERM` if known, otherwise `xterm-256color`.
+  The next interactive `ssh HOST` triggers install.
+- `ssh -V`, `ssh -h`, etc. (no host resolved): pass through.
+- No `infocmp` locally: pass through.
+
+Per-call escape: prefix with `GHOSTEL_SSH_KEEP_TERM=1` to bypass
+the wrapper entirely.
+
+##### Manual install (no auto-machinery)
+
+If you'd rather not have ghostel touch remote hosts (and don't want
+the auto-cache), set `(setq ghostel-ssh-install-terminfo nil)` and
+install the entry yourself once per host.
+
+Pipe the local entry across:
+```bash
+infocmp -x xterm-ghostty | ssh REMOTE 'mkdir -p ~/.terminfo && tic -x -'
+```
+
+Or copy the bundled compiled binary from the package directory:
+```bash
+ssh REMOTE 'mkdir -p ~/.terminfo/x'
+scp <package-dir>/terminfo/x/xterm-ghostty REMOTE:~/.terminfo/x/
+# Ghostty also looks in 78/ on macOS:
+ssh REMOTE 'uname' | grep -q Darwin && {
+    ssh REMOTE 'mkdir -p ~/.terminfo/78'
+    scp <package-dir>/terminfo/78/xterm-ghostty REMOTE:~/.terminfo/78/
+}
+```
+
+After this, every shell on the remote sees `xterm-ghostty` and
+ghostel's outbound ssh wrapper is unnecessary.
+
+##### Drop the Ghostty advertisement entirely
+
+Set `(setq ghostel-term "xterm-256color")` to drop `TERM=xterm-ghostty`
+locally.  No advertisement, no terminfo gymnastics, no synchronized
+output fast-path either.
+
 ### Rendering
 - Incremental redraw — only dirty rows are re-rendered
 - Timer-based batched updates with adaptive frame rate
@@ -441,6 +558,8 @@ individual faces with `M-x customize-face`.
 |----------------------------------|----------------------|----------------------------------------------------------|
 | `ghostel-module-auto-install`    | `ask`                | What to do when native module is missing (`ask`, `download`, `compile`, `nil`) |
 | `ghostel-shell`                  | `$SHELL`             | Shell program to run                                     |
+| `ghostel-term`                   | `"xterm-ghostty"`    | Value of `TERM` for spawned processes.  Default uses the bundled terminfo so apps can detect ghostel's full capability set.  Set to `"xterm-256color"` to fall back (drops `TERMINFO` and `TERM_PROGRAM=ghostty` too) |
+| `ghostel-ssh-install-terminfo`   | `auto`               | Install `xterm-ghostty` terminfo on remote hosts as needed.  `auto` follows `ghostel-tramp-shell-integration`.  Affects both TRAMP-launched ghostel (push terminfo over the existing TRAMP connection) and outbound `ssh` from a local buffer (install via `tic` on first connection, cache in `~/.cache/ghostel/ssh-terminfo-cache`).  Per-call ssh override: `GHOSTEL_SSH_KEEP_TERM=1` |
 | `ghostel-tramp-shells`           | `(see below)`        | Shell to use per TRAMP method (with login-shell detection) |
 | `ghostel-shell-integration`      | `t`                  | Auto-inject shell integration                            |
 | `ghostel-tramp-default-method`   | `nil`                | TRAMP method for new remote paths from OSC 7 (nil uses `tramp-default-method`) |
@@ -513,6 +632,7 @@ When `evil-ghostel-mode` is active:
 | `M-x ghostel-force-redraw`     | Force a full terminal redraw                 |
 | `M-x ghostel-debug-typing-latency` | Measure per-keystroke typing latency     |
 | `M-x ghostel-sync-theme`       | Re-sync color palette after theme change     |
+| `M-x ghostel-ssh-clear-terminfo-cache` | Clear outbound-ssh terminfo install cache (force re-probe) |
 | `M-x ghostel-download-module`  | Download pre-built native module             |
 | `M-x ghostel-module-compile`   | Compile native module from source            |
 
@@ -558,6 +678,12 @@ user, so multi-line shell scripts are passed through verbatim and
 no shell-integration setup is required.  The process sentinel
 delivers the real exit status.
 
+`ghostel-compile` inherits the same `TERM=xterm-ghostty` and
+`TERMINFO=...` env as `M-x ghostel`, so build output gets
+synchronized output, true color, etc.  If a test runner or build
+tool gets confused by the unfamiliar `TERM`, set
+`(setq ghostel-term "xterm-256color")`.
+
 ```elisp
 (require 'ghostel-compile)
 

etc/ghostel.bash

@@ -63,6 +63,118 @@ PROMPT_COMMAND="__ghostel_wrapped_prompt_command"
 
 trap '__ghostel_preexec' DEBUG
 
+# Outbound `ssh' wrapper.  Activated when the elisp side sets
+# `ghostel-ssh-install-terminfo' (which exports
+# GHOSTEL_SSH_INSTALL_TERMINFO).
+#
+# On first connection to a host the wrapper probes whether
+# xterm-ghostty terminfo is present, installs it via `tic' if not,
+# caches the outcome under $XDG_CACHE_HOME/ghostel/ssh-terminfo-cache
+# (key includes a hash of the local terminfo so libghostty bumps
+# auto-invalidate the cache), and connects with TERM=xterm-ghostty.
+# Subsequent connections hit the cache.  Failures (no `tic' on remote,
+# no write access) cache a skip marker and downgrade to xterm-256color.
+#
+# Per-call escape hatch: prefix `ssh' with GHOSTEL_SSH_KEEP_TERM=1 to
+# bypass the wrapper entirely.
+if [[ -n "$GHOSTEL_SSH_INSTALL_TERMINFO" ]]; then
+    ssh() {
+        # Escape hatch + need infocmp locally to do anything useful.
+        if [[ -n "$GHOSTEL_SSH_KEEP_TERM" ]] || \
+               ! builtin command -v infocmp >/dev/null 2>&1; then
+            builtin command ssh "$@"
+            return
+        fi
+
+        # Resolve the canonical target (normalises ssh_config aliases).
+        local _user="" _host="" _port="" _k _v
+        while IFS=' ' read -r _k _v; do
+            case "$_k" in
+                user)     _user=$_v ;;
+                hostname) _host=$_v ;;
+                port)     _port=$_v ;;
+            esac
+            [[ -n $_user && -n $_host && -n $_port ]] && break
+        done < <(builtin command ssh -G "$@" 2>/dev/null)
+
+        # No host (e.g. `ssh -V`, `ssh -h`): pass through.
+        if [[ -z $_host ]]; then
+            builtin command ssh "$@"
+            return
+        fi
+
+        local _target="$_user@$_host:$_port"
+        local _hash
+        _hash=$(infocmp -0 -x xterm-ghostty 2>/dev/null \
+                    | cksum 2>/dev/null | awk '{print $1}')
+        local _cache_dir="${XDG_CACHE_HOME:-$HOME/.cache}/ghostel"
+        local _cache="$_cache_dir/ssh-terminfo-cache"
+        local _key="$_target:$_hash"
+
+        # Cache hit?
+        if [[ -r $_cache ]]; then
+            if grep -Fxq "$_key ok" "$_cache" 2>/dev/null; then
+                TERM=xterm-ghostty builtin command ssh "$@"
+                return
+            fi
+            if grep -Fxq "$_key skip" "$_cache" 2>/dev/null; then
+                TERM=xterm-256color builtin command ssh "$@"
+                return
+            fi
+        fi
+
+        # Skip install when the user passed a remote command — combining
+        # our install script with their command via the same ssh
+        # invocation is fragile.  The next interactive `ssh HOST' will
+        # trigger install.
+        local _positional=0 _skip=0 _arg
+        for _arg in "$@"; do
+            if (( _skip )); then _skip=0; continue; fi
+            case "$_arg" in
+                -[bcDEeFIiJLlmOoPpQRSWw]) _skip=1 ;;
+                -*) ;;
+                *) ((_positional++)) ;;
+            esac
+        done
+
+        if (( _positional > 1 )); then
+            TERM=xterm-256color builtin command ssh "$@"
+            return
+        fi
+
+        # Combined probe + install in a single setup ssh invocation.
+        # Mkdir-as-lock so concurrent first-time `ssh HOST' from two
+        # ghostel buffers don't both spawn a setup connection.
+        builtin command mkdir -p "$_cache_dir" 2>/dev/null
+        # Lock keyed on (target, hash) so concurrent calls to the same
+        # target serialize, but different targets run in parallel.
+        local _lock="$_cache_dir/.lock.$_target.$_hash"
+        if ! builtin command mkdir "$_lock" 2>/dev/null; then
+            TERM=xterm-256color builtin command ssh "$@"
+            return
+        fi
+        # No `trap RETURN' — bash's RETURN trap is shell-global and
+        # would clobber any pre-existing user trap.  Cleanup is
+        # explicit at each return point.
+        if infocmp -0 -x xterm-ghostty 2>/dev/null \
+                | builtin command ssh "$@" '
+                    infocmp xterm-ghostty >/dev/null 2>&1 && exit 0
+                    command -v tic >/dev/null 2>&1 || exit 1
+                    mkdir -p "$HOME/.terminfo" && tic -x - >/dev/null 2>&1
+                  ' >/dev/null 2>&1; then
+            builtin echo "$_key ok" >> "$_cache"
+            builtin command rmdir "$_lock" 2>/dev/null
+            TERM=xterm-ghostty builtin command ssh "$@"
+        else
+            builtin echo "ghostel: failed to install xterm-ghostty terminfo on $_host \
+(no \`tic' on remote?), using xterm-256color." >&2
+            builtin echo "$_key skip" >> "$_cache"
+            builtin command rmdir "$_lock" 2>/dev/null
+            TERM=xterm-256color builtin command ssh "$@"
+        fi
+    }
+fi
+
 # Call an Emacs Elisp function from the shell.
 # Usage: ghostel_cmd FUNCTION [ARGS...]
 # The function must be in `ghostel-eval-cmds'.