feat(host/gamescope): headless game mode that follows the box + matches the client

Make Steam game mode work on a display-less streaming host and stream it at the
client's resolution:

* Ship /etc/gamescope-session-plus/sessions.d/steam (packaging/bazzite/
  gamescope-headless-session, installed by the RPM + Arch PKGBUILD): fall back to
  gamescope's headless backend when no display is connected, so "Switch to Game
  Mode" boots offscreen instead of crashing on the missing panel (and 5-striking
  back to desktop). No-op on display-attached boxes; only sets unset values so
  the host's per-client mode still wins.

* Default Bazzite/SteamOS to ATTACH (PUNKTFUNK_GAMESCOPE_ATTACH=1 in host.env):
  the box owns its session (Desktop<->Game, persistent), the host follows +
  captures it and never tears it down — so switching is rock-solid and a
  disconnect leaves the box in its mode (reconnect returns there).

* Resize-on-attach (gamescope.rs): on connect, ensure the box's own game-mode
  session runs at the CLIENT's resolution — reuse it when already matching (fast
  path, no restart), else reconfigure + restart the box's own autologin
  gamescope-session-plus@<client> at the client mode (cooperative: no competing
  unit, so no autologin-respawn fight). Detect the live gamescope's -W/-H via
  argv[0] in /proc (its /proc/<pid>/exe is unreadable for that process).

Validated live on a headless bazzite-deck-nvidia box: game mode boots headless +
stable (0 strikes); the host attaches + streams video/audio/EIS input; a
5120x1440 client reuses the matching session and streams at 5120x1440.

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

packaging/arch/PKGBUILD

@@ -72,6 +72,8 @@ package_punktfunk-host() {
               'xdg-desktop-portal-wlr: portal for the headless Sway session helper'
               'punktfunk-web: browser management console (device pairing + status)')
   install=punktfunk-host.install
+  # User-editable config: the headless game-mode drop-in (see below) — don't clobber local edits.
+  backup=('etc/gamescope-session-plus/sessions.d/steam')
   local R; R="$(_repo)"; local T="$srcdir/target/release"
 
   install -Dm0755 "$T/punktfunk-host"                 "$pkgdir/usr/bin/punktfunk-host"
@@ -100,6 +102,11 @@ package_punktfunk-host() {
   install -Dm0644 "$R/scripts/host.env.example"              "$pkgdir/usr/share/punktfunk/host.env.example"
   install -Dm0644 "$R/packaging/bazzite/host.env"            "$pkgdir/usr/share/punktfunk/host.env.bazzite"
   install -Dm0644 "$R/packaging/kde/host.env"                "$pkgdir/usr/share/punktfunk/host.env.kde"
+  # Headless GAME-mode fix: gamescope-session-plus drop-in that uses the headless backend when no
+  # display is connected (so SteamOS/Bazzite "Switch to Game Mode" works on a display-less streaming
+  # host). No-op on display-attached boxes; sourced as /etc/gamescope-session-plus/sessions.d/steam.
+  install -Dm0644 "$R/packaging/bazzite/gamescope-headless-session" \
+    "$pkgdir/etc/gamescope-session-plus/sessions.d/steam"
   install -Dm0644 "$R/api/openapi.json"                 "$pkgdir/usr/share/punktfunk/openapi.json"
   install -Dm0644 "$R/LICENSE-MIT"    "$pkgdir/usr/share/licenses/punktfunk-host/LICENSE-MIT"
   install -Dm0644 "$R/LICENSE-APACHE" "$pkgdir/usr/share/licenses/punktfunk-host/LICENSE-APACHE"

packaging/bazzite/gamescope-headless-session

@@ -0,0 +1,22 @@
+# punktfunk: headless game-mode fallback for gamescope-session-plus.
+#
+# Installed as /etc/gamescope-session-plus/sessions.d/steam. The gamescope-session-plus launcher
+# SOURCES this (shell, with `set -a` so assignments auto-export) AFTER its /usr/share defaults, so it
+# can override the session's gamescope flags.
+#
+# Why: on a box with NO connected display (a dedicated streaming host), the stock Steam game mode runs
+# gamescope's DRM backend against a physical panel (`--prefer-output *,eDP-1`). With nothing to scan
+# out, gamescope crashes on launch; after 5 strikes Bazzite/SteamOS force-selects the desktop session
+# and "Switch to Game Mode" appears broken. Falling back to gamescope's HEADLESS backend makes game
+# mode render entirely offscreen and expose a PipeWire node, which the punktfunk host captures and
+# streams — full gamescope game mode (per-game res / FSR / HDR / VRR / frame-limit), no monitor needed.
+#
+# Safe by construction:
+#   * NO-OP when any display is connected -> the normal DRM game mode runs unchanged.
+#   * Only sets values that are still unset (`: "${VAR:=...}"`), so the punktfunk host's per-client
+#     mode (SCREEN_WIDTH/SCREEN_HEIGHT injected via systemd-run for a managed session) still wins.
+if ! grep -qx connected /sys/class/drm/*/status 2>/dev/null; then
+    : "${BACKEND:=headless}"
+    : "${SCREEN_WIDTH:=1920}"
+    : "${SCREEN_HEIGHT:=1080}"
+fi

packaging/bazzite/host.env

@@ -20,13 +20,25 @@ PUNKTFUNK_ZEROCOPY=1
 #   PUNKTFUNK_COMPOSITOR=kwin|mutter|wlroots|gamescope
 #   PUNKTFUNK_INPUT_BACKEND=libei|wlr|gamescope|uinput
 #
-# In Gaming Mode the host MANAGES a gamescope-session-plus at the CLIENT's resolution by default
-# (tears the TV's autologin down on connect; restores it on a debounced idle, reused on a quick
-# reconnect). To instead ATTACH to the running TV session at its own mode (couch-on-TV — gaming
-# stays live on the panel, no Steam restart), set:
-#   PUNKTFUNK_GAMESCOPE_ATTACH=1
-#   PUNKTFUNK_GAMESCOPE_APP=steam -gamepadui   # only for an ad-hoc bare-spawn fallback
+# GAME MODE = ATTACH (the box owns its session; the host follows). The box decides whether it's in
+# Steam Gaming Mode or a Desktop — you switch with the normal Steam UI / "Switch to Desktop". The
+# host just ATTACHES to whatever's live and captures it; it never tears the session down or relaunches
+# it. So switching Desktop<->Game is rock-solid, and when you disconnect the box STAYS in its current
+# mode — reconnecting drops you right back where you were. The streamed resolution in game mode is the
+# box's gamescope mode (see SCREEN_WIDTH/HEIGHT in /etc/gamescope-session-plus/sessions.d/steam).
+PUNKTFUNK_GAMESCOPE_ATTACH=1
+#
+# Opt OUT to the MANAGED model instead (host tears the box's gamescope down on connect and launches
+# its OWN at the CLIENT's exact resolution; restores on a debounced idle). Client-mode-following, but
+# it does not coexist with a box-owned game-mode session — pick one:
+#   PUNKTFUNK_GAMESCOPE_MANAGED=1   # (and remove PUNKTFUNK_GAMESCOPE_ATTACH above)
 #
 # Follow a Gaming<->Desktop switch MID-STREAM (rebuild the backend in place, no reconnect). This is
 # ON BY DEFAULT on Bazzite/SteamOS (the host detects the platform); set =0 to disable it:
 #   PUNKTFUNK_SESSION_WATCH=0
+#
+# HEADLESS GAME MODE: on a box with no display attached, Bazzite's "Switch to Game Mode" normally
+# crashes (gamescope's DRM backend has no panel to drive). The host package ships
+# /etc/gamescope-session-plus/sessions.d/steam, which auto-falls-back to gamescope's HEADLESS backend
+# when no display is connected — so game mode boots offscreen and streams, with no config here. It's a
+# no-op on display-attached boxes. (The host then auto-detects Gaming and streams it.)

packaging/rpm/punktfunk.spec

@@ -233,6 +233,13 @@ install -Dm0644 packaging/kde/host.env                 %{buildroot}%{_datadir}/%
 # screencast/virtual-output grant ships as io.unom.Punktfunk.Host.desktop, installed above).
 install -d %{buildroot}%{_datadir}/%{name}/bazzite
 install -Dm0755 packaging/bazzite/kde-desktop-setup.sh %{buildroot}%{_datadir}/%{name}/bazzite/kde-desktop-setup.sh
+# Headless GAME-mode fix: a gamescope-session-plus sessions.d drop-in that falls back to gamescope's
+# headless backend when no display is connected (so "Switch to Game Mode" works on a display-less
+# streaming host instead of crashing + 5-striking back to desktop). No-op on display-attached boxes.
+# Sourced by gamescope-session-plus as /etc/gamescope-session-plus/sessions.d/steam (after its
+# /usr/share defaults). Harmless on non-gamescope systems (the file is simply never read).
+install -Dm0644 packaging/bazzite/gamescope-headless-session \
+                %{buildroot}/etc/gamescope-session-plus/sessions.d/steam
 install -Dm0644 api/openapi.json                  %{buildroot}%{_datadir}/%{name}/openapi.json
 
 %if %{with web}
@@ -262,6 +269,9 @@ install -Dm0644 web/web.env.example                %{buildroot}%{_datadir}/punkt
 %{_userunitdir}/punktfunk-host.service
 %{_userunitdir}/punktfunk-kde-session.service
 %{_datadir}/applications/io.unom.Punktfunk.Host.desktop
+%dir /etc/gamescope-session-plus
+%dir /etc/gamescope-session-plus/sessions.d
+%config(noreplace) /etc/gamescope-session-plus/sessions.d/steam
 %dir %{_datadir}/%{name}
 %{_datadir}/%{name}/*