feat(packaging): a desktop-login host restarts with its desktop

The shipped unit's PartOf=punktfunk-kde-session.service covers the
APPLIANCE route, where we start the compositor ourselves. A host on a
machine somebody logs into has no such unit: when Plasma or GNOME
restarts, the daemon keeps running while holding a Wayland socket and a
portal D-Bus connection that both died with the old compositor, and it
cannot recover either in-process. It fails quietly — the host still
listens, still answers, and every session it then serves dies at capture.
A host that mirrors a monitor idles for days between sessions, which is
the shape that finds this at the worst moment.

The drop-in binds the host to graphical-session.target: PartOf takes it
down with the session, WantedBy brings it back with the new one. Shipped
under /usr/share rather than as an active drop-in, because it is wrong
for the appliance route (which may never reach that target at all, and
would then leave the host permanently stopped) — the operator opts in.

Closes the restart half of design/per-monitor-portal-capture.md §6.

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

scripts/punktfunk-host-desktop-session.conf

@@ -0,0 +1,42 @@
+# systemd USER drop-in: bind the host to the DESKTOP LOGIN session's lifetime.
+#
+# Install (on top of punktfunk-host.service):
+#   mkdir -p ~/.config/systemd/user/punktfunk-host.service.d
+#   cp scripts/punktfunk-host-desktop-session.conf \
+#      ~/.config/systemd/user/punktfunk-host.service.d/desktop-session.conf
+#   systemctl --user daemon-reload
+#   systemctl --user reenable punktfunk-host      # picks up the [Install] below
+#   systemctl --user restart punktfunk-host
+#
+# WHY: the shipped unit's `PartOf=punktfunk-kde-session.service` covers the APPLIANCE route, where we
+# start the compositor ourselves. A host on a machine somebody logs into has no such unit — so when
+# Plasma or GNOME restarts (a crash, a session logout/login, "restart the shell"), the daemon keeps
+# running while holding a Wayland socket and a portal D-Bus connection that both died with the old
+# compositor. It cannot recover those in-process. It is a quiet failure — the host still listens, still
+# answers, and every session it then serves fails at capture. A host that mirrors a monitor
+# (design/per-monitor-portal-capture.md) sits idle for days between sessions, which is exactly the
+# shape that gets discovered at the worst moment.
+#
+# `graphical-session.target` is the session's own lifetime, reached by GNOME and Plasma under systemd
+# session management. `PartOf=` stops us when it goes down; the `WantedBy=` below starts us again when
+# the new session brings it back up. So a compositor restart becomes a host restart, with a fresh
+# connection to the compositor that is actually there.
+#
+# NOT for the appliance/headless route (a pinned PUNKTFUNK_COMPOSITOR, punktfunk-kde-session.service,
+# a gamescope box): those have their own session unit and may never reach graphical-session.target at
+# all, and this drop-in would leave the host permanently stopped.
+#
+# Sway / Hyprland / any session NOT managed by systemd never reaches graphical-session.target either.
+# There the drop-in is harmless but does nothing; start the host from the compositor's own config
+# instead (`exec systemctl --user start punktfunk-host` after `systemctl --user import-environment`),
+# so it dies and comes back with the session.
+
+[Unit]
+After=graphical-session.target
+PartOf=graphical-session.target
+
+[Install]
+# In ADDITION to the base unit's WantedBy=default.target, so the host still comes up at login even
+# before the graphical session is ready — it listens without touching the compositor and only opens
+# one per client connect, so an early start costs nothing.
+WantedBy=graphical-session.target

scripts/punktfunk-host.service

@@ -8,6 +8,18 @@
 #   cp scripts/host.env.example ~/.config/punktfunk/host.env   # defaults are right for a desktop
 #   systemctl --user daemon-reload && systemctl --user enable --now punktfunk-host
 #
+# On that desktop-login route, ALSO install scripts/punktfunk-host-desktop-session.conf as a drop-in:
+# it binds the host to graphical-session.target, so a Plasma/GNOME restart restarts the host instead
+# of leaving it holding a dead Wayland socket + portal connection (the PartOf= below only covers the
+# appliance route, where we start the compositor ourselves). The drop-in's header has the commands.
+#
+# The host does NOT need the login shell's environment: it detects the live session itself per
+# connect and derives WAYLAND_DISPLAY, XDG_RUNTIME_DIR, DBUS_SESSION_BUS_ADDRESS, XDG_CURRENT_DESKTOP,
+# HYPRLAND_INSTANCE_SIGNATURE and SWAYSOCK from the running compositor (vdisplay::apply_session_env).
+# So host.env carries policy, not session plumbing, and `systemctl --user import-environment` is not
+# a prerequisite — the host pushes the live values into the manager env itself when a session switch
+# needs the portal to re-read them.
+#
 # Self-contained boot appliance (no login, no manual steps after boot). These routes PIN the
 # backend via PUNKTFUNK_COMPOSITOR — correct for a dedicated single-session box, but it turns off
 # live-session auto-detection, so never do it on a desktop that switches sessions (Game Mode etc.):