feat(headless-kde): reliable bring-up — readiness probe, fix portal ordering/env (roadmap #1 phase 1)

Headless KDE startup was a chain of timing-sensitive handoffs gated by a blind `sleep 2`,
the dominant source of black screens. Phase-1 fixes:

- New `punktfunk-host probe-compositor` subcommand: exits 0 iff the detected compositor is
  up AND ready to create a virtual output now. KWin gets a real check (connect + registry
  roundtrip + the privileged zkde_screencast global must be advertised — what the backend
  needs); gamescope/Mutter/wlroots create on demand so the probe just confirms Linux.
  (vdisplay::probe dispatcher + kwin::probe; reuses kwin.rs's existing roundtrip path.)
- run-headless-kde.sh: replace `sleep 2` with an active readiness wait (poll probe-compositor
  until ready, 30s deadline, and bail with kwin's log if kwin_wayland exits during init).
  Move the portal restart to AFTER readiness, and precede it with `systemctl --user
  import-environment` + `dbus-update-activation-environment` (the missing env import — the
  Sway script does this; without it a restarted portal inherits a stale/empty WAYLAND_DISPLAY,
  which is the "streams but eats no input/audio" failure). kwin's stderr → a log file.

Validated: probe-compositor exits 0 "Kwin ready" against the live session, exit 1 with a
clear diagnostic when the compositor is absent. 114 tests green, clippy/fmt clean.

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

crates/punktfunk-host/src/main.rs

@@ -27,7 +27,7 @@ mod vdisplay;
 #[cfg(target_os = "linux")]
 mod zerocopy;
 
-use anyhow::{bail, Result};
+use anyhow::{bail, Context, Result};
 use encode::Codec;
 use m0::{Options, Source};
 use std::path::PathBuf;
@@ -68,6 +68,15 @@ fn real_main() -> Result<()> {
         // Zero-copy FFI/GPU probe: init the EGL importer + CUDA context (no capture needed).
         #[cfg(target_os = "linux")]
         Some("zerocopy-probe") => zerocopy::probe(),
+        // Compositor readiness probe: exit 0 iff the (detected or PUNKTFUNK_COMPOSITOR-forced)
+        // compositor is up and able to create a virtual output *now*. A session-bringup
+        // script polls this to gate on real readiness instead of a blind `sleep`.
+        Some("probe-compositor") => {
+            let compositor = vdisplay::detect()?;
+            vdisplay::probe(compositor).with_context(|| format!("{compositor:?} not ready"))?;
+            println!("{compositor:?} ready");
+            Ok(())
+        }
         // M0 pipeline spike.
         Some("m0") => m0::run(parse_m0(&args[1..])?),
         // M3: native punktfunk/1 host (QUIC control plane + UDP data plane).
@@ -308,6 +317,7 @@ USAGE:
                                   + the management REST API
     punktfunk-host openapi            print the management API's OpenAPI document (codegen)
     punktfunk-host m3-host [OPTIONS]  native punktfunk/1 host (QUIC control plane + UDP data plane)
+    punktfunk-host probe-compositor   exit 0 iff the compositor is up + ready (session-bringup gate)
     punktfunk-host m0 [OPTIONS]       M0 capture→encode→file pipeline spike
 
 SERVE OPTIONS: