fix(ssh): fallback terminal for tmux on ghostty

Author: acmore

docs/troubleshooting.md

@@ -41,6 +41,7 @@
 - For unstable links, increase:
   - `spec.ssh.keepAliveIntervalSeconds`
   - `spec.ssh.keepAliveTimeoutSeconds`
+- If tmux login fails with `missing or unsuitable terminal` (for example `xterm-ghostty`), upgrade to a sidecar image that includes terminal fallback handling, then recreate the pod with `okdev down && okdev up`.
 
 ## Local State Files
 

infra/sidecar/entrypoint.sh

@@ -80,6 +80,11 @@ fi
 # Interactive login shell in dev container.
 # Wrap in tmux if enabled (OKDEV_TMUX=1) and not opted out (OKDEV_NO_TMUX!=1).
 if [ "${OKDEV_TMUX_FLAG:-}" = "1" ] && [ "${OKDEV_NO_TMUX:-}" != "1" ] && command -v tmux >/dev/null 2>&1; then
+  # Some modern terminals (for example Ghostty) may not exist in the sidecar
+  # terminfo database. Use a widely available fallback for tmux startup.
+  if [ "${TERM:-}" = "xterm-ghostty" ]; then
+    export TERM="xterm-256color"
+  fi
   if nsenter --target "$DEV_PID" --mount -- test -x /bin/bash 2>/dev/null; then
     exec tmux new-session -A -s okdev "nsenter --target $DEV_PID --mount --uts --ipc --pid -- /bin/bash -l"
   else