install the tmux config where tmux actually reads it

tmux 3.1 added an XDG location and it takes PRECEDENCE over ~/.tmux.conf.
Verified on 3.4 here by writing a different marker into each and asking tmux
which one it ended up with:

  both present       -> ~/.config/tmux/tmux.conf
  only ~/.tmux.conf  -> ~/.tmux.conf
  only the XDG one   -> the XDG one

So the Shell section writing ~/.tmux.conf on a machine that already has the XDG
file produced a file tmux will never read, and reported "tmux config installed"
having changed nothing anybody could observe. That is the worst shape a config
step can have: it looks done.

tmux_config_target now picks the path tmux will actually load — the existing XDG
file if there is one, otherwise ~/.tmux.conf, which is still what every guide
names and what a machine with neither should get. When both exist the section
says so out loud before targeting the winner, because "your other file wins" is
not something anyone infers from a success message.

Also removed an untracked duplicate at scripts/setup/.tmux.conf. The one the
script installs is scripts/setup/machine-setup/.tmux.conf — SCRIPT_DIR is the
machine-setup directory — and two identical copies with only one of them read is
the drift this whole evening has been about.

Nothing to change about the config itself: the tracked copy is already byte-for-
byte the owner's own ~/.tmux.conf.

Not yet wired into per-user provisioning. src/servers/shell-skel/ seeds a zshrc
for a member and has no tmux config beside it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

scripts/setup/machine-setup/lib/files.sh

@@ -125,3 +125,38 @@ append_once() {
     echo "$end"
   } >>"$file"
 }
+
+# -----------------------------------------------------------------------------
+# Where tmux actually reads its config
+# -----------------------------------------------------------------------------
+#
+# tmux 3.1 added an XDG location and it takes PRECEDENCE. Verified on 3.4 by
+# creating both and asking tmux which marker it ended up with:
+#
+#   both present            -> ~/.config/tmux/tmux.conf
+#   only ~/.tmux.conf       -> ~/.tmux.conf
+#   only the XDG one        -> the XDG one
+#
+# So installing to ~/.tmux.conf on a machine that has the XDG file writes a file
+# tmux will never read, and the script would report success having changed
+# nothing anybody can see. That is the failure this exists to prevent.
+#
+# Rules, in order:
+#   1. an existing XDG config wins  -> that is their real config, target it
+#   2. an existing ~/.tmux.conf     -> target it, since it is what tmux reads
+#   3. neither                      -> ~/.tmux.conf, the path every guide names
+tmux_config_target() {
+  local home="$1"
+  local xdg="${XDG_CONFIG_HOME:-$home/.config}/tmux/tmux.conf"
+  if [[ -f "$xdg" ]]; then
+    echo "$xdg"
+  else
+    echo "$home/.tmux.conf"
+  fi
+}
+
+# True when a ~/.tmux.conf would be shadowed by an XDG config that already exists.
+tmux_dot_conf_is_shadowed() {
+  local home="$1"
+  [[ -f "${XDG_CONFIG_HOME:-$home/.config}/tmux/tmux.conf" && -f "$home/.tmux.conf" ]]
+}

scripts/setup/machine-setup/machine-setup.sh

@@ -2226,10 +2226,20 @@ if ! skip; then
     fi
 
     if [[ -r "$SCRIPT_DIR/.tmux.conf" ]]; then
-      install_config "$SCRIPT_DIR/.tmux.conf" "${USER_HOME}/.tmux.conf" "$USERNAME" && RC=0 || RC=$?
+      # Not always ~/.tmux.conf — see tmux_config_target. tmux 3.1+ prefers
+      # ~/.config/tmux/tmux.conf, so writing the old path on a machine that has
+      # the new one produces a file tmux never reads and a success message that
+      # means nothing.
+      TMUX_TARGET="$(tmux_config_target "$USER_HOME")"
+      if tmux_dot_conf_is_shadowed "$USER_HOME"; then
+        warn "you have BOTH ~/.tmux.conf and ~/.config/tmux/tmux.conf — tmux reads the second"
+        echo "     Targeting the one it actually reads: ${TMUX_TARGET}"
+      fi
+      install -d -m 0755 -o "$USERNAME" -g "$(user_group)" "$(dirname "$TMUX_TARGET")"
+      install_config "$SCRIPT_DIR/.tmux.conf" "$TMUX_TARGET" "$USERNAME" && RC=0 || RC=$?
       case $RC in
-        0) ok "tmux config installed" ;;
+        0) ok "tmux config installed — ${TMUX_TARGET}" ;;
-        1) echo "     tmux config already matches" ;;
+        1) echo "     tmux config already matches (${TMUX_TARGET})" ;;
       esac
     fi