feat(decky): full-featured Gaming-Mode client — fullscreen page, pairing, focus-correct launch

The plugin was a QAM launcher whose stream never appeared, with no
pairing. Three fixes, plus a headless --pair mode on the GTK client:

- Stream actually starts (MoonDeck's proven mechanism): gamescope only
  focuses the process tree Steam launched via reaper, so a flatpak
  spawned from the (root) backend is invisible. The frontend now
  registers ONE hidden non-Steam shortcut pointing at bin/punktfunkrun.sh,
  passes the host as the shortcut's Steam launch options, and starts it
  with SteamClient.Apps.RunGame — gamescope then fullscreen-focuses it.
  The wrapper execs `flatpak run io.unom.Punktfunk --connect <host>`.
- Fullscreen page: routerHook.addRoute("/punktfunk") — host list,
  per-host Pair/Stream, and a settings section (resolution/refresh/
  bitrate/gamepad/mic, written to client-gtk-settings.json).
- Pairing: a gamepad-navigable PIN keypad. The host shows the PIN; the
  backend runs the SPAKE2 ceremony headlessly via the client's new
  `--pair <PIN> --connect host` CLI mode (app.rs), persisting the host
  as paired so the stream then connects silently. Same flatpak =>
  shared identity store, verified live (ceremony against a real host).
- Backend (main.py): discover / pair / runner_info / get_settings /
  set_settings / kill_stream; uses DECKY_USER_HOME so paths resolve to
  the deck user's flatpak install regardless of the plugin's root flag.

CI (decky.yml) and the sideload packager now ship bin/punktfunkrun.sh.
The Steam-shortcut launch and headless-pairing env follow MoonDeck
exactly but need a Deck in Gaming Mode to fully confirm.

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

crates/punktfunk-client-linux/src/app.rs

@@ -36,6 +36,11 @@ pub fn run() -> glib::ExitCode {
             tracing_subscriber::EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()),
         )
         .init();
+    // Headless pairing path (no GTK window): `--pair <PIN> --connect host[:port] [--name N]`.
+    // Used by the Decky plugin (a GTK dialog can't pop under gamescope) and for scripting.
+    if let Some(pin) = arg_value("--pair") {
+        return headless_pair(&pin);
+    }
     let app = adw::Application::builder().application_id(APP_ID).build();
     app.connect_activate(build_ui);
     // GTK doesn't see our argv (`--connect` is handled in `build_ui`); an empty argv also
@@ -43,6 +48,66 @@ pub fn run() -> glib::ExitCode {
     app.run_with_args(&[] as &[&str])
 }
 
+/// The value following `flag` in argv, if present (`--flag value`).
+fn arg_value(flag: &str) -> Option<String> {
+    std::env::args()
+        .skip_while(|a| a != flag)
+        .nth(1)
+        .filter(|v| !v.starts_with("--"))
+}
+
+/// Run the SPAKE2 PIN ceremony without a GTK window and persist the verified host to the
+/// known-hosts store as paired, so a later `--connect` connects silently. Same identity
+/// store the streaming path uses (same binary), so pairing here makes the stream work.
+/// Prints a one-line `paired <addr>:<port> fp=<hex>` on success; exits non-zero on failure.
+fn headless_pair(pin: &str) -> glib::ExitCode {
+    let Some(target) = arg_value("--connect") else {
+        eprintln!("--pair requires --connect host[:port]");
+        return glib::ExitCode::FAILURE;
+    };
+    let (addr, port) = match target.rsplit_once(':') {
+        Some((a, p)) => (a.to_string(), p.parse().unwrap_or(9777)),
+        None => (target.clone(), 9777),
+    };
+    // The label the HOST stores this client under (its paired-devices list).
+    let name = arg_value("--name").unwrap_or_else(|| "Steam Deck".to_string());
+
+    let identity = match crate::trust::load_or_create_identity() {
+        Ok(i) => i,
+        Err(e) => {
+            eprintln!("client identity: {e:#}");
+            return glib::ExitCode::FAILURE;
+        }
+    };
+    match NativeClient::pair(
+        &addr,
+        port,
+        (&identity.0, &identity.1),
+        pin.trim(),
+        &name,
+        std::time::Duration::from_secs(90),
+    ) {
+        Ok(fp) => {
+            let fp_hex = crate::trust::hex(&fp);
+            let mut known = KnownHosts::load();
+            known.upsert(KnownHost {
+                name: arg_value("--host-label").unwrap_or_else(|| addr.clone()),
+                addr: addr.clone(),
+                port,
+                fp_hex: fp_hex.clone(),
+                paired: true,
+            });
+            let _ = known.save();
+            println!("paired {addr}:{port} fp={fp_hex}");
+            glib::ExitCode::SUCCESS
+        }
+        Err(e) => {
+            eprintln!("pairing failed: {e:?} (wrong PIN, or pairing not armed on the host?)");
+            glib::ExitCode::FAILURE
+        }
+    }
+}
+
 /// `--connect host[:port]` — skip the hosts page and start a session immediately
 /// (scripting + headless testing). Trust follows the same rules as a manual entry: a host
 /// already pinned at this address connects silently on its stored pin; an unknown host is