chore: consolidate all in-progress parallel-session WIP

Wholesale commit of every uncommitted change across the tree, at the user's
explicit request — host refactor-campaign W1 (native.rs facade + native/ dir,
library/ + mgmt/ splits), Android, core. These streams were mid-flight and not
individually built/tested together; this supersedes the per-session HOLD
markers. Consolidating so everything lands on main in one pass.

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

crates/punktfunk-host/src/mgmt/auth.rs

@@ -0,0 +1,121 @@
+//! Auth gate for the management API `/api/v1` routes: paired client cert (mTLS, from anywhere)
+//! or the bearer token (loopback peers only). Split out of the `mgmt` facade (plan §W5).
+
+use super::shared::*;
+use crate::gamestream::tls::PeerAddr;
+use crate::gamestream::tls::PeerCertFingerprint;
+use axum::extract::Request;
+use axum::http::header;
+use axum::http::Method;
+use axum::middleware::Next;
+use sha2::{Digest, Sha256};
+
+/// Auth gate on the `/api/v1` routes: a paired client cert (mTLS, from anywhere) or the bearer token
+/// (from a **loopback** peer only) — required always (the host runs with a token by construction).
+/// `/api/v1/health` stays open for probes; `/api/v1/local/summary` is open to loopback peers only
+/// (the tray icon's status source). The cert path authorizes only the read-only allowlist
+/// ([`cert_may_access`]); the bearer path authorizes the full admin surface and is therefore confined
+/// to loopback so it is never LAN-exposed even when the listener binds all interfaces by default.
+pub(crate) async fn require_auth(
+    State(st): State<Arc<MgmtState>>,
+    req: Request,
+    next: Next,
+) -> Response {
+    if req.uri().path() == "/api/v1/health" {
+        return next.run(req).await; // liveness probe is always open
+    }
+    // The tray icon's status source: non-sensitive counts/booleans only, unauthenticated but
+    // confined to LOOPBACK peers. The bearer-token file (and cert.pem) are SYSTEM/Administrators-
+    // DACL'd on Windows, so the per-user tray process cannot authenticate — this one narrow
+    // read-only route is deliberately all it needs. Not on the cert allowlist: LAN mTLS clients
+    // already have the richer `/status`. (No PeerAddr ⇒ a unit test → treat as loopback, matching
+    // the bearer path below.)
+    if req.uri().path() == "/api/v1/local/summary" {
+        let from_loopback = req
+            .extensions()
+            .get::<PeerAddr>()
+            .is_none_or(|a| a.0.ip().is_loopback());
+        return if from_loopback {
+            next.run(req).await
+        } else {
+            api_error(
+                StatusCode::UNAUTHORIZED,
+                "the local summary is loopback-only",
+            )
+        };
+    }
+    // A paired native client authenticates by its mTLS certificate — the same identity + trust the
+    // QUIC data plane uses. But "paired to STREAM" is not "paired to ADMINISTER": a streaming cert
+    // authorizes only the safe, read-only status routes, NOT state-changing or pairing-administration
+    // routes (which would let one paired client unpair others, read/arm the pairing PIN, stop
+    // sessions, or edit the library). Everything outside the allowlist requires the operator's bearer
+    // token. The fingerprint is attached by `serve_https` from the verified peer cert.
+    if let Some(PeerCertFingerprint(Some(fp))) = req.extensions().get::<PeerCertFingerprint>() {
+        if cert_may_access(req.method(), req.uri().path())
+            && st.native.as_ref().is_some_and(|n| n.is_paired(fp))
+        {
+            return next.run(req).await;
+        }
+    }
+    // Otherwise require the bearer token (the web console / admin) — but only from a LOOPBACK peer.
+    // The token authorizes the full admin surface, so confining it to loopback keeps that surface off
+    // the LAN even though the listener now binds all interfaces by default (so paired clients can
+    // browse the library). The web console BFF — the sole token holder — always connects over
+    // loopback, so nothing first-party is affected; a LAN caller must use a paired client cert and is
+    // limited to the read-only allowlist above. (No PeerAddr ⇒ a non-`serve_https` caller, e.g. a unit
+    // test → treat as loopback so handler tests still authenticate by token.)
+    let from_loopback = req
+        .extensions()
+        .get::<PeerAddr>()
+        .is_none_or(|a| a.0.ip().is_loopback());
+    if !from_loopback {
+        return api_error(
+            StatusCode::UNAUTHORIZED,
+            "the admin API is loopback-only — a LAN client must present a paired client certificate",
+        );
+    }
+    // `run` always passes a token, so no-token means a misconfigured caller (e.g. a test constructing
+    // `app` directly) — deny.
+    let Some(expected) = st.token.as_deref() else {
+        return api_error(StatusCode::UNAUTHORIZED, "authentication required");
+    };
+    let presented = req
+        .headers()
+        .get(header::AUTHORIZATION)
+        .and_then(|v| v.to_str().ok())
+        .and_then(|v| v.strip_prefix("Bearer "));
+    match presented {
+        Some(token) if token_eq(token, expected) => next.run(req).await,
+        _ => api_error(
+            StatusCode::UNAUTHORIZED,
+            "missing or invalid credentials (a paired client cert, or a bearer token)",
+        ),
+    }
+}
+
+/// Which routes a paired *streaming* cert (mTLS, no bearer token) may reach: a small allowlist of
+/// safe, read-only status routes only. Deny-by-default — every state-changing route and every route
+/// that exposes a pairing PIN or the pending-approval queue requires the operator's bearer token, so
+/// a streaming client can't administer the host (unpair others, arm/read the PIN, stop sessions,
+/// edit the library). `/health` is handled separately (always open).
+pub(crate) fn cert_may_access(method: &Method, path: &str) -> bool {
+    method == Method::GET
+        && (matches!(
+            path,
+            "/api/v1/host"
+                | "/api/v1/compositors"
+                | "/api/v1/status"
+                | "/api/v1/clients"
+                | "/api/v1/native/clients"
+                // The native clients browse the game library with their cert (no bearer token); the
+                // library MUTATIONS (POST/PUT/DELETE /library/custom) stay token-only via the exact
+                // GET-path match above.
+                | "/api/v1/library"
+        ) || path.starts_with("/api/v1/library/art/"))
+}
+
+/// Compare SHA-256 digests instead of the strings — constant-time with respect to the
+/// secret without pulling in a ct-eq dependency.
+pub(crate) fn token_eq(presented: &str, expected: &str) -> bool {
+    Sha256::digest(presented.as_bytes()) == Sha256::digest(expected.as_bytes())
+}

crates/punktfunk-host/src/mgmt/clients.rs

@@ -0,0 +1,174 @@
+//! Client/pairing-tagged management endpoints: paired Moonlight clients and the GameStream
+//! pairing PIN flow. Split out of the `mgmt` facade (plan §W5).
+
+use super::shared::*;
+use sha2::{Digest, Sha256};
+
+/// A paired (certificate-pinned) Moonlight client.
+#[derive(Serialize, ToSchema)]
+pub(crate) struct PairedClient {
+    /// Lowercase hex SHA-256 of the client certificate DER — the client's stable id here.
+    #[schema(example = "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08")]
+    fingerprint: String,
+    /// Certificate subject (e.g. `CN=NVIDIA GameStream Client`), if the DER parses.
+    subject: Option<String>,
+    /// Certificate validity start (unix seconds).
+    not_before_unix: Option<i64>,
+    /// Certificate validity end (unix seconds).
+    not_after_unix: Option<i64>,
+}
+
+/// Pairing-flow status.
+#[derive(Serialize, ToSchema)]
+pub(crate) struct PairingStatus {
+    /// True while a pairing handshake is parked waiting for the user's PIN.
+    pin_pending: bool,
+}
+
+/// The PIN Moonlight displays during pairing.
+#[derive(Deserialize, ToSchema)]
+pub(crate) struct SubmitPin {
+    /// 1–16 ASCII digits (Moonlight shows 4).
+    #[schema(example = "1234")]
+    pin: String,
+}
+
+/// List paired clients
+#[utoipa::path(
+    get,
+    path = "/clients",
+    tag = "clients",
+    operation_id = "listPairedClients",
+    responses(
+        (status = OK, description = "All certificate-pinned clients", body = [PairedClient]),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn list_paired_clients(
+    State(st): State<Arc<MgmtState>>,
+) -> Json<Vec<PairedClient>> {
+    let ders = st.app.paired.lock().unwrap().clone();
+    Json(ders.iter().map(|der| client_info(der)).collect())
+}
+
+pub(crate) fn client_info(der: &[u8]) -> PairedClient {
+    let fingerprint = hex::encode(Sha256::digest(der));
+    match x509_parser::parse_x509_certificate(der) {
+        Ok((_, x509)) => PairedClient {
+            fingerprint,
+            subject: Some(x509.subject().to_string()),
+            not_before_unix: Some(x509.validity().not_before.timestamp()),
+            not_after_unix: Some(x509.validity().not_after.timestamp()),
+        },
+        Err(_) => PairedClient {
+            fingerprint,
+            subject: None,
+            not_before_unix: None,
+            not_after_unix: None,
+        },
+    }
+}
+
+/// Unpair a client
+///
+/// Removes the client's certificate from the pairing store. Caveat: the nvhttp TLS layer
+/// does not yet reject unlisted certificates (`gamestream/tls.rs` accepts any well-formed
+/// client cert — a planned hardening step), so until that lands this removes the client
+/// from the listing without severing its ability to reconnect.
+#[utoipa::path(
+    delete,
+    path = "/clients/{fingerprint}",
+    tag = "clients",
+    operation_id = "unpairClient",
+    params(
+        ("fingerprint" = String, Path,
+         description = "Hex SHA-256 fingerprint of the client certificate DER (64 chars, case-insensitive)")
+    ),
+    responses(
+        (status = NO_CONTENT, description = "Client unpaired"),
+        (status = BAD_REQUEST, description = "Malformed fingerprint", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+        (status = NOT_FOUND, description = "No paired client with that fingerprint", body = ApiError),
+    )
+)]
+pub(crate) async fn unpair_client(
+    State(st): State<Arc<MgmtState>>,
+    Path(fingerprint): Path<String>,
+) -> Response {
+    if fingerprint.len() != 64 || !fingerprint.bytes().all(|b| b.is_ascii_hexdigit()) {
+        return api_error(
+            StatusCode::BAD_REQUEST,
+            "fingerprint must be the 64-char hex SHA-256 of the client certificate DER",
+        );
+    }
+    let mut paired = st.app.paired.lock().unwrap();
+    let before = paired.len();
+    paired.retain(|der| !hex::encode(Sha256::digest(der)).eq_ignore_ascii_case(&fingerprint));
+    if paired.len() < before {
+        tracing::info!(fingerprint, "management API: client unpaired");
+        StatusCode::NO_CONTENT.into_response()
+    } else {
+        api_error(
+            StatusCode::NOT_FOUND,
+            "no paired client with that fingerprint",
+        )
+    }
+}
+
+/// Pairing-flow status
+///
+/// Poll this to know when to prompt the user for the PIN Moonlight displays.
+#[utoipa::path(
+    get,
+    path = "/pair",
+    tag = "pairing",
+    operation_id = "getPairingStatus",
+    responses(
+        (status = OK, description = "Whether a pairing handshake is waiting for a PIN", body = PairingStatus),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn get_pairing_status(State(st): State<Arc<MgmtState>>) -> Json<PairingStatus> {
+    Json(PairingStatus {
+        pin_pending: st.app.pairing.pin.awaiting_pin(),
+    })
+}
+
+/// Submit the pairing PIN
+///
+/// Delivers the PIN the Moonlight client is displaying, completing the out-of-band half
+/// of the pairing handshake.
+#[utoipa::path(
+    post,
+    path = "/pair/pin",
+    tag = "pairing",
+    operation_id = "submitPairingPin",
+    request_body = SubmitPin,
+    responses(
+        (status = NO_CONTENT, description = "PIN delivered to the waiting handshake"),
+        (status = BAD_REQUEST, description = "Malformed PIN or unparseable JSON body", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+        (status = CONFLICT, description = "No pairing handshake is waiting for a PIN", body = ApiError),
+        (status = UNSUPPORTED_MEDIA_TYPE, description = "Body is not application/json", body = ApiError),
+        (status = UNPROCESSABLE_ENTITY, description = "JSON body does not match the schema", body = ApiError),
+    )
+)]
+pub(crate) async fn submit_pairing_pin(
+    State(st): State<Arc<MgmtState>>,
+    ApiJson(req): ApiJson<SubmitPin>,
+) -> Response {
+    let pin = req.pin.trim();
+    if pin.is_empty() || pin.len() > 16 || !pin.bytes().all(|b| b.is_ascii_digit()) {
+        return api_error(StatusCode::BAD_REQUEST, "pin must be 1-16 ASCII digits");
+    }
+    if !st.app.pairing.pin.awaiting_pin() {
+        // Refusing (rather than parking the PIN) prevents a stale PIN from silently
+        // satisfying a *future* pairing attempt.
+        return api_error(
+            StatusCode::CONFLICT,
+            "no pairing handshake is waiting for a PIN",
+        );
+    }
+    st.app.pairing.pin.submit(pin.to_string());
+    StatusCode::NO_CONTENT.into_response()
+}

crates/punktfunk-host/src/mgmt/display.rs

@@ -0,0 +1,416 @@
+//! Display-tagged management endpoints: virtual-display policy, state, layout, and custom
+//! presets. Split out of the `mgmt` facade (plan §W5).
+
+use super::shared::*;
+
+/// One preset's human-facing description + the fields it expands to, so the console can render a
+/// preset picker with an accurate "what this does" preview without hardcoding the expansion.
+#[derive(Serialize, ToSchema)]
+pub(crate) struct PresetInfo {
+    /// The preset id (`default` | `gaming-rig` | `shared-desktop` | `hotdesk` | `workstation`).
+    id: String,
+    /// One-line story shown next to the option.
+    summary: String,
+    /// The effective policy this preset expands to (the same fields a `custom` policy carries).
+    fields: crate::vdisplay::policy::EffectivePolicy,
+}
+
+/// Full display-management state for the console: the stored policy, every preset's expansion, the
+/// resolved effective policy, and which options this build actually enforces yet (Stage 0 wires
+/// keep-alive linger + topology; the rest are stored but not yet acted on).
+#[derive(Serialize, ToSchema)]
+pub(crate) struct DisplaySettingsState {
+    /// The stored policy (preset + custom fields), or the built-in default when unconfigured.
+    settings: crate::vdisplay::policy::DisplayPolicy,
+    /// True once a `display-settings.json` exists (the console has configured this host).
+    configured: bool,
+    /// The effective (preset-expanded) policy currently in force.
+    effective: crate::vdisplay::policy::EffectivePolicy,
+    /// Every named preset and what it expands to (for the picker's preview).
+    presets: Vec<PresetInfo>,
+    /// The operator's saved custom presets (`display-presets.json`) — named field-bundles rendered
+    /// alongside the built-ins. Managed via `POST/PUT/DELETE /display/presets`; applied by writing a
+    /// `Custom` policy carrying the preset's fields.
+    custom_presets: Vec<crate::vdisplay::policy::CustomPreset>,
+    /// Option names this build enforces right now. All five axes are now acted on (keep_alive +
+    /// topology since Stage 0-2, identity Stage 3, mode_conflict Stage 4, layout Stage 5) — the console
+    /// reads this to know which controls are live vs. "coming soon" (per-backend nuance, e.g. layout
+    /// position apply being KWin-only, is reported per display in `/display/state`).
+    enforced: Vec<String>,
+}
+
+pub(crate) fn preset_summary(id: &str) -> &'static str {
+    match id {
+        "default" => "Good for most setups. Reconnects resume quickly, the stream is the whole desktop, and extra viewers each get their own screen.",
+        "gaming-rig" => "For a machine with no monitor that you only stream from. The game keeps running when you disconnect, and whoever connects next takes it over.",
+        "shared-desktop" => "For a PC you also use in person. Your real monitors are never blanked or left with a leftover display, and extra viewers each get their own screen.",
+        "hotdesk" => "One person at a time — roam between your own devices with an instant reconnect. Anyone else is told the box is busy.",
+        "workstation" => "Your multi-monitor daily driver. Displays come back exactly where you arranged them, each client keeps its own settings, and the desktop is yours alone.",
+        _ => "",
+    }
+}
+
+pub(crate) fn display_settings_state() -> DisplaySettingsState {
+    use crate::vdisplay::policy::{self, Preset};
+    let store = policy::prefs();
+    let settings = store.get();
+    let configured = store.configured().is_some();
+    let presets = [
+        ("default", Preset::Default),
+        ("gaming-rig", Preset::GamingRig),
+        ("shared-desktop", Preset::SharedDesktop),
+        ("hotdesk", Preset::Hotdesk),
+        ("workstation", Preset::Workstation),
+    ]
+    .into_iter()
+    .filter_map(|(id, p)| {
+        policy::preset_fields(p).map(|e| PresetInfo {
+            id: id.to_string(),
+            summary: preset_summary(id).to_string(),
+            fields: e,
+        })
+    })
+    .collect();
+    DisplaySettingsState {
+        effective: settings.effective(),
+        settings,
+        configured,
+        presets,
+        custom_presets: policy::load_custom_presets(),
+        enforced: vec![
+            "keep_alive".into(),
+            "topology".into(),
+            "mode_conflict".into(),
+            "identity".into(),
+            "layout".into(),
+            "game_session".into(),
+            // EXPERIMENTAL, Windows-only in effect: acted on at the `exclusive` isolate
+            // (`vdisplay/windows/manager.rs`); stored-but-inert elsewhere.
+            "ddc_power_off".into(),
+            "pnp_disable_monitors".into(),
+        ],
+    }
+}
+
+/// Display-management policy
+///
+/// The stored virtual-display policy (lifecycle, topology, conflict handling, identity, layout),
+/// every preset's expansion, and which options this build enforces yet. See
+/// `design/display-management.md`.
+#[utoipa::path(
+    get,
+    path = "/display/settings",
+    tag = "display",
+    operation_id = "getDisplaySettings",
+    responses(
+        (status = OK, description = "Stored policy + preset expansions + enforced options", body = DisplaySettingsState),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn get_display_settings() -> Json<DisplaySettingsState> {
+    Json(display_settings_state())
+}
+
+/// Set the display-management policy
+///
+/// Persists a new policy (validated + clamped) and applies it from the next connect/teardown — a
+/// running session keeps the display it opened on. `keep_alive: forever` (the gaming-rig preset) is
+/// honored (the display is Pinned; free it via `POST /display/release`).
+#[utoipa::path(
+    put,
+    path = "/display/settings",
+    tag = "display",
+    operation_id = "setDisplaySettings",
+    request_body = crate::vdisplay::policy::DisplayPolicy,
+    responses(
+        (status = OK, description = "Policy stored; the new state", body = DisplaySettingsState),
+        (status = BAD_REQUEST, description = "Malformed policy body", body = ApiError),
+        (status = INTERNAL_SERVER_ERROR, description = "Policy could not be persisted", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn set_display_settings(
+    ApiJson(policy): ApiJson<crate::vdisplay::policy::DisplayPolicy>,
+) -> Response {
+    // `keep_alive: forever` (the gaming-rig preset) is now honored: the display is Pinned (Linux
+    // registry + Windows `MgrState::Pinned`) and freed via `POST /display/release` (the escape hatch).
+    if let Err(e) = crate::vdisplay::policy::prefs().set(policy) {
+        return api_error(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            &format!("persist display policy: {e:#}"),
+        );
+    }
+    tracing::info!("management API: display policy updated");
+    Json(display_settings_state()).into_response()
+}
+
+/// One live or kept virtual display.
+#[derive(Serialize, ToSchema)]
+pub(crate) struct ApiDisplayInfo {
+    /// Stable-enough id for the `/display/release` `slot` argument.
+    slot: u64,
+    /// Backend name (`pf-vdisplay`, `kwin`, …).
+    backend: String,
+    /// `WIDTHxHEIGHT@HZ`.
+    mode: String,
+    /// `active` | `lingering` | `pinned`.
+    state: String,
+    /// Milliseconds until a lingering display is torn down (absent when active/pinned).
+    expires_in_ms: Option<u64>,
+    /// Live sessions holding the display.
+    sessions: u32,
+    /// Short client label, when the owner tracks it.
+    client: Option<String>,
+    /// Display group (shared desktop) id — several displays with the same group form one desktop (§6A).
+    group: u32,
+    /// This display's ordinal within its group, in acquire order (0-based).
+    display_index: u32,
+    /// Desktop-space top-left `x` (auto-row or the console's manual arrangement, §6.2).
+    x: i32,
+    /// Desktop-space top-left `y`.
+    y: i32,
+    /// Stable per-client identity slot keying persistent config + manual layout (absent = shared/anonymous).
+    identity_slot: Option<u32>,
+    /// Effective topology for this display's group (`extend` | `primary` | `exclusive`).
+    topology: String,
+}
+
+/// The host's managed virtual displays right now.
+#[derive(Serialize, ToSchema)]
+pub(crate) struct DisplayStateResponse {
+    displays: Vec<ApiDisplayInfo>,
+}
+
+/// Request body for `releaseDisplay`.
+#[derive(Deserialize, ToSchema)]
+pub(crate) struct ReleaseDisplayRequest {
+    /// Slot to release (see `state`); omit to release **all** kept displays.
+    #[serde(default)]
+    slot: Option<u64>,
+}
+
+/// Result of a `/display/release`.
+#[derive(Serialize, ToSchema)]
+pub(crate) struct ReleaseDisplayResult {
+    /// Number of kept displays torn down.
+    released: usize,
+}
+
+/// Live virtual displays
+///
+/// The host's managed virtual displays right now — active (streaming), lingering (kept after
+/// disconnect, counting down to teardown), or pinned (kept indefinitely). See
+/// `design/display-management.md`.
+#[utoipa::path(
+    get,
+    path = "/display/state",
+    tag = "display",
+    operation_id = "getDisplayState",
+    responses(
+        (status = OK, description = "The live/kept virtual displays", body = DisplayStateResponse),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn get_display_state() -> Json<DisplayStateResponse> {
+    let snap = crate::vdisplay::registry::snapshot();
+    Json(DisplayStateResponse {
+        displays: snap
+            .displays
+            .into_iter()
+            .map(|d| ApiDisplayInfo {
+                slot: d.slot,
+                backend: d.backend,
+                mode: format!("{}x{}@{}", d.mode.0, d.mode.1, d.mode.2),
+                state: d.state,
+                expires_in_ms: d.expires_in_ms,
+                sessions: d.sessions,
+                client: d.client,
+                group: d.group,
+                display_index: d.display_index,
+                x: d.position.0,
+                y: d.position.1,
+                identity_slot: d.identity_slot,
+                topology: d.topology,
+            })
+            .collect(),
+    })
+}
+
+/// Release kept virtual displays
+///
+/// Tear down lingering/pinned displays now — so a physical-screen user gets their screen back
+/// without waiting out the linger. `slot` releases one; omit it to release all kept displays.
+/// Active (streaming) displays are never torn down here (that is session control).
+#[utoipa::path(
+    post,
+    path = "/display/release",
+    tag = "display",
+    operation_id = "releaseDisplay",
+    request_body = ReleaseDisplayRequest,
+    responses(
+        (status = OK, description = "The number of kept displays released", body = ReleaseDisplayResult),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn release_display(
+    ApiJson(req): ApiJson<ReleaseDisplayRequest>,
+) -> Json<ReleaseDisplayResult> {
+    let released = crate::vdisplay::registry::release(req.slot);
+    tracing::info!(slot = ?req.slot, released, "management API: display release");
+    Json(ReleaseDisplayResult { released })
+}
+
+/// Request body for `setDisplayLayout`: per-identity-slot desktop offsets, keyed by the identity-slot
+/// id as a string (the same id `/display/state` reports as `identity_slot`).
+#[derive(Deserialize, ToSchema)]
+pub(crate) struct DisplayLayoutRequest {
+    /// `{"<identity_slot>": {"x": …, "y": …}}` — where each arranged display's top-left sits.
+    #[serde(default)]
+    positions: std::collections::BTreeMap<String, crate::vdisplay::policy::Position>,
+}
+
+/// Arrange virtual displays
+///
+/// Set the **manual** desktop arrangement — per-identity-slot `(x, y)` offsets so a multi-monitor
+/// group (§6A/§6B) comes back where the operator placed it. Persisted into the policy's layout block
+/// and switched to manual mode; applied from the next connect (a live group re-applies on its next
+/// acquire). Locks in the current effective behavior as explicit fields, so arranging displays never
+/// silently changes keep-alive/topology/conflict/identity. See `design/display-management.md` §6.2.
+#[utoipa::path(
+    put,
+    path = "/display/layout",
+    tag = "display",
+    operation_id = "setDisplayLayout",
+    request_body = DisplayLayoutRequest,
+    responses(
+        (status = OK, description = "Layout stored; the new settings state", body = DisplaySettingsState),
+        (status = INTERNAL_SERVER_ERROR, description = "Layout could not be persisted", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn set_display_layout(ApiJson(req): ApiJson<DisplayLayoutRequest>) -> Response {
+    let store = crate::vdisplay::policy::prefs();
+    // Lock the current effective behavior into explicit fields + set the manual arrangement (pure
+    // transform, unit-tested in `policy.rs`) — so arranging displays is orthogonal to the other policy
+    // axes. (`effective` keep_alive is never `Forever` via the API — the settings PUT rejects it.)
+    let policy = store.get().effective().with_manual_layout(
+        req.positions,
+        store.game_session(),
+        store.ddc_power_off(),
+        store.pnp_disable_monitors(),
+    );
+    if let Err(e) = store.set(policy) {
+        return api_error(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            &format!("persist display layout: {e:#}"),
+        );
+    }
+    tracing::info!(
+        positions = display_settings_state().settings.layout.positions.len(),
+        "management API: display layout updated"
+    );
+    Json(display_settings_state()).into_response()
+}
+
+/// List the saved custom presets
+///
+/// The operator's named field-bundles (`display-presets.json`). These also ride the
+/// `GET /display/settings` response (`custom_presets`), so the console rarely needs this directly.
+#[utoipa::path(
+    get,
+    path = "/display/presets",
+    tag = "display",
+    operation_id = "listCustomPresets",
+    responses(
+        (status = OK, description = "The saved custom presets", body = Vec<crate::vdisplay::policy::CustomPreset>),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn list_custom_presets() -> Json<Vec<crate::vdisplay::policy::CustomPreset>> {
+    Json(crate::vdisplay::policy::load_custom_presets())
+}
+
+/// Save a custom preset
+///
+/// Stores a named bundle of the display-behavior axes (+ the game-session axis) the operator can
+/// apply later. The host assigns a stable id, returned in the body. Applying a preset is a
+/// `PUT /display/settings` with a `Custom` policy carrying its `fields` — no separate apply route.
+#[utoipa::path(
+    post,
+    path = "/display/presets",
+    tag = "display",
+    operation_id = "createCustomPreset",
+    request_body = crate::vdisplay::policy::CustomPresetInput,
+    responses(
+        (status = CREATED, description = "Preset created", body = crate::vdisplay::policy::CustomPreset),
+        (status = BAD_REQUEST, description = "Empty name", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+        (status = INTERNAL_SERVER_ERROR, description = "Could not persist the catalog", body = ApiError),
+    )
+)]
+pub(crate) async fn create_custom_preset(
+    ApiJson(input): ApiJson<crate::vdisplay::policy::CustomPresetInput>,
+) -> Response {
+    if input.name.trim().is_empty() {
+        return api_error(StatusCode::BAD_REQUEST, "preset name must not be empty");
+    }
+    match crate::vdisplay::policy::add_custom_preset(input) {
+        Ok(preset) => (StatusCode::CREATED, Json(preset)).into_response(),
+        Err(e) => api_error(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string()),
+    }
+}
+
+/// Update a custom preset
+#[utoipa::path(
+    put,
+    path = "/display/presets/{id}",
+    tag = "display",
+    operation_id = "updateCustomPreset",
+    params(("id" = String, Path, description = "The custom preset id")),
+    request_body = crate::vdisplay::policy::CustomPresetInput,
+    responses(
+        (status = OK, description = "Preset updated", body = crate::vdisplay::policy::CustomPreset),
+        (status = BAD_REQUEST, description = "Empty name", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+        (status = NOT_FOUND, description = "No custom preset with that id", body = ApiError),
+        (status = INTERNAL_SERVER_ERROR, description = "Could not persist the catalog", body = ApiError),
+    )
+)]
+pub(crate) async fn update_custom_preset(
+    Path(id): Path<String>,
+    ApiJson(input): ApiJson<crate::vdisplay::policy::CustomPresetInput>,
+) -> Response {
+    if input.name.trim().is_empty() {
+        return api_error(StatusCode::BAD_REQUEST, "preset name must not be empty");
+    }
+    match crate::vdisplay::policy::update_custom_preset(&id, input) {
+        Ok(Some(preset)) => Json(preset).into_response(),
+        Ok(None) => api_error(StatusCode::NOT_FOUND, "no custom preset with that id"),
+        Err(e) => api_error(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string()),
+    }
+}
+
+/// Delete a custom preset
+///
+/// Removes it from the catalog. The active policy is untouched — if this preset was the one applied,
+/// the running behavior stays exactly as it was (the catalog and `display-settings.json` are decoupled).
+#[utoipa::path(
+    delete,
+    path = "/display/presets/{id}",
+    tag = "display",
+    operation_id = "deleteCustomPreset",
+    params(("id" = String, Path, description = "The custom preset id")),
+    responses(
+        (status = NO_CONTENT, description = "Preset deleted"),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+        (status = NOT_FOUND, description = "No custom preset with that id", body = ApiError),
+        (status = INTERNAL_SERVER_ERROR, description = "Could not persist the catalog", body = ApiError),
+    )
+)]
+pub(crate) async fn delete_custom_preset(Path(id): Path<String>) -> Response {
+    match crate::vdisplay::policy::delete_custom_preset(&id) {
+        Ok(true) => StatusCode::NO_CONTENT.into_response(),
+        Ok(false) => api_error(StatusCode::NOT_FOUND, "no custom preset with that id"),
+        Err(e) => api_error(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string()),
+    }
+}

crates/punktfunk-host/src/mgmt/gpu.rs

@@ -0,0 +1,236 @@
+//! GPU-tagged management endpoints: inventory + automatic/preferred selection. Split out of the
+//! `mgmt` facade (plan §W5).
+
+use super::shared::*;
+
+/// One hardware GPU on the host (software/WARP adapters are never listed).
+#[derive(Serialize, ToSchema)]
+pub(crate) struct ApiGpu {
+    /// Stable identifier (`vendorid-deviceid-occurrence`, hex PCI ids) — pass to `setGpuPreference`.
+    /// Stable across reboots and driver updates, unlike an adapter index or LUID.
+    #[schema(example = "10de-2c05-0")]
+    id: String,
+    /// Adapter/marketing name.
+    #[schema(example = "NVIDIA GeForce RTX 5070 Ti")]
+    name: String,
+    /// `nvidia` | `amd` | `intel` | `other`.
+    vendor: String,
+    /// Dedicated VRAM in MiB (0 where the platform doesn't expose it).
+    vram_mb: u64,
+}
+
+/// The GPU the **next** session's pipeline will be created on, and why. (A preference change
+/// applies to the next session; a running session keeps the GPU it opened on.)
+#[derive(Serialize, ToSchema)]
+pub(crate) struct ApiSelectedGpu {
+    id: String,
+    name: String,
+    /// `nvidia` | `amd` | `intel` | `other`.
+    vendor: String,
+    /// Why this GPU was selected: `preference` (the manual choice), `env`
+    /// (`PUNKTFUNK_RENDER_ADAPTER`), `auto` (max dedicated VRAM / platform default), or
+    /// `preference_missing` (a manual choice is set but that GPU is absent — auto-selected
+    /// instead so the host keeps streaming).
+    source: String,
+}
+
+/// The GPU live sessions are encoding on right now.
+#[derive(Serialize, ToSchema)]
+pub(crate) struct ApiActiveGpu {
+    /// Stable id matching an entry of `gpus` (empty for the CPU/software encoder).
+    id: String,
+    name: String,
+    /// `nvidia` | `amd` | `intel` | `other`.
+    vendor: String,
+    /// The encode backend in use (`nvenc` | `amf` | `qsv` | `vaapi` | `software`).
+    backend: String,
+    /// Number of live encode sessions on it.
+    sessions: u32,
+}
+
+/// Full GPU-selection state for the console: inventory, the persisted preference, what the next
+/// session will use, and what is in use right now.
+#[derive(Serialize, ToSchema)]
+pub(crate) struct GpuState {
+    /// The host's hardware GPUs.
+    gpus: Vec<ApiGpu>,
+    /// `auto` or `manual`.
+    mode: String,
+    /// The manually preferred GPU's stable id, when one is stored (kept while `mode` is `auto` so
+    /// a console can offer returning to it). May reference a GPU that is currently absent.
+    preferred_id: Option<String>,
+    /// The stored name of the preferred GPU (a usable label even when it is absent).
+    preferred_name: Option<String>,
+    /// Whether the preferred GPU is currently present.
+    preferred_available: bool,
+    /// `PUNKTFUNK_RENDER_ADAPTER` (the host.env pin), when set — it applies while `mode` is
+    /// `auto`; a manual preference overrides it.
+    env_override: Option<String>,
+    /// The GPU the next session will use.
+    selected: Option<ApiSelectedGpu>,
+    /// The GPU live sessions use right now (absent while nothing is streaming).
+    active: Option<ApiActiveGpu>,
+}
+
+/// Request body for `setGpuPreference`.
+#[derive(Deserialize, ToSchema)]
+pub(crate) struct SetGpuPreference {
+    /// `auto` (env pin, else max dedicated VRAM — the default) or `manual`.
+    #[schema(example = "manual")]
+    mode: String,
+    /// Required when `mode` is `manual`: the stable `id` of a currently listed GPU
+    /// (see `listGpus`).
+    #[schema(example = "10de-2c05-0")]
+    gpu_id: Option<String>,
+}
+
+/// Build the [`GpuState`] snapshot (shared by the GET and the PUT's response).
+pub(crate) fn gpu_state() -> GpuState {
+    let gpus = crate::gpu::enumerate();
+    let pref = crate::gpu::prefs().get();
+    let (preferred_id, preferred_name, preferred_available) = match &pref.gpu {
+        Some(want) => {
+            let found = crate::gpu::find_preferred(&gpus, want);
+            let id = match found {
+                // Canonical: the present GPU's id (identity may have matched loosely).
+                Some(i) => gpus[i].id.clone(),
+                None => format!(
+                    "{:04x}-{:04x}-{}",
+                    want.vendor_id, want.device_id, want.occurrence
+                ),
+            };
+            let name = match found {
+                Some(i) => gpus[i].name.clone(),
+                None => want.name.clone(),
+            };
+            (Some(id), Some(name), found.is_some())
+        }
+        None => (None, None, false),
+    };
+    let selected = crate::gpu::selected_gpu().map(|sel| ApiSelectedGpu {
+        vendor: sel.info.vendor_tag().into(),
+        id: sel.info.id,
+        name: sel.info.name,
+        source: sel.source.tag().into(),
+    });
+    let active = crate::gpu::active().and_then(|(g, sessions)| {
+        (sessions > 0).then(|| ApiActiveGpu {
+            vendor: crate::gpu::vendor_tag(g.vendor_id).into(),
+            id: g.id,
+            name: g.name,
+            backend: g.backend.into(),
+            sessions,
+        })
+    });
+    GpuState {
+        gpus: gpus
+            .into_iter()
+            .map(|g| ApiGpu {
+                vendor: g.vendor_tag().into(),
+                vram_mb: g.vram_bytes / (1024 * 1024),
+                id: g.id,
+                name: g.name,
+            })
+            .collect(),
+        mode: match pref.mode {
+            crate::gpu::GpuMode::Auto => "auto".into(),
+            crate::gpu::GpuMode::Manual => "manual".into(),
+        },
+        preferred_id,
+        preferred_name,
+        preferred_available,
+        env_override: crate::config::config()
+            .render_adapter
+            .clone()
+            .filter(|s| !s.is_empty()),
+        selected,
+        active,
+    }
+}
+
+/// GPU inventory and selection
+///
+/// Lists the host's hardware GPUs, the persisted auto/manual preference, the GPU the next session
+/// will use (and why), and the GPU live sessions encode on right now.
+#[utoipa::path(
+    get,
+    path = "/gpus",
+    tag = "gpu",
+    operation_id = "listGpus",
+    responses(
+        (status = OK, description = "GPU inventory + selection state", body = GpuState),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn list_gpus() -> Json<GpuState> {
+    Json(gpu_state())
+}
+
+/// Set the GPU preference
+///
+/// `auto` restores automatic selection (`PUNKTFUNK_RENDER_ADAPTER` pin, else max dedicated VRAM);
+/// `manual` pins capture + encode to the given GPU. Persisted across restarts; applies to the
+/// **next** session (a running session keeps its GPU). If the preferred GPU is absent at session
+/// start the host falls back to automatic selection rather than failing.
+#[utoipa::path(
+    put,
+    path = "/gpus/preference",
+    tag = "gpu",
+    operation_id = "setGpuPreference",
+    request_body = SetGpuPreference,
+    responses(
+        (status = OK, description = "Preference stored; the new selection state", body = GpuState),
+        (status = BAD_REQUEST, description = "Unknown mode, or `gpu_id` missing / not a listed GPU", body = ApiError),
+        (status = INTERNAL_SERVER_ERROR, description = "Preference could not be persisted", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn set_gpu_preference(ApiJson(req): ApiJson<SetGpuPreference>) -> Response {
+    let pref = match req.mode.to_ascii_lowercase().as_str() {
+        "auto" => {
+            // Keep the stored manual pick so the console can offer switching back to it.
+            let mut p = crate::gpu::prefs().get();
+            p.mode = crate::gpu::GpuMode::Auto;
+            p
+        }
+        "manual" => {
+            let Some(id) = req
+                .gpu_id
+                .as_deref()
+                .map(str::trim)
+                .filter(|s| !s.is_empty())
+            else {
+                return api_error(StatusCode::BAD_REQUEST, "mode `manual` requires `gpu_id`");
+            };
+            let Some(g) = crate::gpu::enumerate().into_iter().find(|g| g.id == id) else {
+                return api_error(
+                    StatusCode::BAD_REQUEST,
+                    "gpu_id does not match a present GPU (see GET /gpus)",
+                );
+            };
+            crate::gpu::GpuPreference {
+                mode: crate::gpu::GpuMode::Manual,
+                gpu: Some(crate::gpu::PreferredGpu {
+                    vendor_id: g.vendor_id,
+                    device_id: g.device_id,
+                    occurrence: g.occurrence,
+                    name: g.name,
+                }),
+            }
+        }
+        other => {
+            return api_error(
+                StatusCode::BAD_REQUEST,
+                &format!("unknown mode {other:?} — use `auto` or `manual`"),
+            )
+        }
+    };
+    if let Err(e) = crate::gpu::prefs().set(pref) {
+        return api_error(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            &format!("persist GPU preference: {e:#}"),
+        );
+    }
+    tracing::info!(mode = %req.mode, gpu_id = ?req.gpu_id, "management API: GPU preference updated");
+    Json(gpu_state()).into_response()
+}

crates/punktfunk-host/src/mgmt/host.rs

@@ -0,0 +1,421 @@
+//! Host-tagged management endpoints: identity + capabilities, liveness, compositor list, live
+//! runtime status, and the loopback tray summary. Split out of the `mgmt` facade (plan §W5).
+
+use super::shared::*;
+use crate::encode::Codec;
+use crate::gamestream::APP_VERSION;
+use crate::gamestream::AUDIO_PORT;
+use crate::gamestream::CONTROL_PORT;
+use crate::gamestream::GFE_VERSION;
+use crate::gamestream::RTSP_PORT;
+use crate::gamestream::VIDEO_PORT;
+use std::sync::atomic::Ordering;
+
+/// Liveness + version probe.
+#[derive(Serialize, ToSchema)]
+pub(crate) struct Health {
+    /// Always `"ok"` when the host responds.
+    #[schema(example = "ok")]
+    status: String,
+    /// `punktfunk-host` crate version.
+    version: String,
+    /// `punktfunk-core` C ABI version.
+    abi_version: u32,
+}
+
+/// Host identity and advertised capabilities (static for the life of the process).
+#[derive(Serialize, ToSchema)]
+pub(crate) struct HostInfo {
+    hostname: String,
+    /// Stable per-host id (persisted across restarts), matched on pairing.
+    uniqueid: String,
+    /// Best-effort primary LAN IP.
+    local_ip: String,
+    /// `punktfunk-host` crate version.
+    version: String,
+    /// `punktfunk-core` C ABI version.
+    abi_version: u32,
+    /// GameStream host version advertised to Moonlight clients.
+    app_version: String,
+    /// GFE version advertised to Moonlight clients.
+    gfe_version: String,
+    /// Codecs the host can encode (NVENC).
+    codecs: Vec<ApiCodec>,
+    /// Whether the GameStream/Moonlight-compat planes are running (`--gamestream`). `false` on the
+    /// secure default (native punktfunk/1 only) — a console can hide Moonlight-only UI (e.g. the
+    /// Moonlight PIN pairing card, which could never receive a PIN when this is `false`).
+    gamestream: bool,
+    ports: PortMap,
+}
+
+/// Every port a client integration may need (Moonlight derives the stream ports from the
+/// HTTP base; a control pane should not have to).
+#[derive(Serialize, ToSchema)]
+pub(crate) struct PortMap {
+    /// This management API.
+    mgmt: u16,
+    /// nvhttp plain HTTP (serverinfo, pairing).
+    http: u16,
+    /// nvhttp mutual-TLS HTTPS (post-pairing).
+    https: u16,
+    rtsp: u16,
+    video: u16,
+    control: u16,
+    audio: u16,
+}
+
+/// Video codec identifier. The wire token matches the codec's canonical name used across the
+/// stack (SDP/GameStream advertisement, the stats-capture `CaptureMeta.codec`, and the encoder's
+/// [`Codec::label`]) — notably `H.265` serializes as `"hevc"`, not `"h265"`, so the same codec
+/// reads identically on every console page.
+#[derive(Clone, Copy, Serialize, Deserialize, ToSchema, PartialEq, Eq, Debug)]
+#[serde(rename_all = "lowercase")]
+pub(crate) enum ApiCodec {
+    H264,
+    #[serde(rename = "hevc")]
+    H265,
+    Av1,
+    /// PyroWave — the opt-in wired-LAN intra-only wavelet codec.
+    PyroWave,
+}
+
+impl From<Codec> for ApiCodec {
+    fn from(c: Codec) -> Self {
+        match c {
+            Codec::H264 => ApiCodec::H264,
+            Codec::H265 => ApiCodec::H265,
+            Codec::Av1 => ApiCodec::Av1,
+            Codec::PyroWave => ApiCodec::PyroWave,
+        }
+    }
+}
+
+/// Live host status (changes as clients launch/end sessions).
+#[derive(Serialize, ToSchema)]
+pub(crate) struct RuntimeStatus {
+    /// True while the video stream thread is running.
+    video_streaming: bool,
+    /// True while the audio stream thread is running.
+    audio_streaming: bool,
+    /// True while a pairing handshake is parked waiting for the user's PIN
+    /// (submit it via `POST /api/v1/pair/pin`).
+    pin_pending: bool,
+    /// Number of pinned (paired) client certificates.
+    paired_clients: u32,
+    /// Number of live streaming sessions across BOTH planes (GameStream + native punktfunk/1). The
+    /// native server admits concurrent sessions, so this can exceed 1; `session`/`stream` below
+    /// describe a single representative session for the detail card.
+    active_sessions: u32,
+    /// A representative active session. GameStream's launch (Moonlight `/launch`) when present, else
+    /// the first live native session. `null` when nothing is streaming.
+    session: Option<SessionInfo>,
+    /// The active stream's parameters — RTSP-negotiated for GameStream, or the live native session's
+    /// mode/codec/bitrate. `null` when nothing is streaming.
+    stream: Option<StreamInfo>,
+}
+
+/// Client-requested launch parameters (key material is never exposed here).
+#[derive(Serialize, ToSchema)]
+pub(crate) struct SessionInfo {
+    width: u32,
+    height: u32,
+    fps: u32,
+}
+
+/// RTSP-negotiated stream parameters.
+#[derive(Serialize, ToSchema)]
+pub(crate) struct StreamInfo {
+    width: u32,
+    height: u32,
+    fps: u32,
+    bitrate_kbps: u32,
+    /// Video payload size per packet (bytes).
+    packet_size: u32,
+    /// Client's parity floor per FEC block (`minRequiredFecPackets`).
+    min_fec: u8,
+    codec: ApiCodec,
+}
+
+/// Non-sensitive host status for the local tray icon: counts and booleans only — no PIN values,
+/// no fingerprints, no device names. Served unauthenticated to LOOPBACK peers only (see
+/// `require_auth`): the bearer-token file is SYSTEM/Administrators-DACL'd on Windows, so the
+/// per-user tray process cannot authenticate — this narrow read-only route is its status source.
+#[derive(Serialize, ToSchema)]
+pub(crate) struct LocalSummary {
+    /// Host version (mirrors `/health`).
+    version: String,
+    /// True while the video stream thread is running.
+    video_streaming: bool,
+    /// True while the audio stream thread is running.
+    audio_streaming: bool,
+    /// The active launch session (set by Moonlight's `/launch`, cleared on cancel/stop).
+    session: Option<SessionInfo>,
+    /// Number of pinned (paired) GameStream client certificates.
+    paired_clients: u32,
+    /// Number of paired native (punktfunk/1) devices.
+    native_paired_clients: u32,
+    /// True while a GameStream pairing handshake is parked waiting for the user's PIN.
+    pin_pending: bool,
+    /// Native pairing knocks awaiting the operator's approval (count only).
+    pending_approvals: u32,
+    /// Virtual displays being KEPT with no live session — lingering (keep-alive window) or pinned
+    /// (`keep_alive: forever`). Non-zero means a display (and, exclusive, your physical monitors) is
+    /// held; the tray surfaces it + a one-click release. Active (in-use) displays are not counted.
+    kept_displays: u32,
+    /// Other Moonlight-compatible hosts (Sunshine/Apollo/…) detected on this machine at startup —
+    /// running one alongside Punktfunk is unsupported. Compact labels (e.g. `Sunshine (running)`);
+    /// the tray/console surface them so the clash is visible before pairing silently fails.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    conflicts: Vec<String>,
+}
+
+/// Liveness probe
+///
+/// Always available without authentication.
+#[utoipa::path(
+    get,
+    path = "/health",
+    tag = "host",
+    operation_id = "getHealth",
+    // Override the document-global bearerAuth: this route is exempt in `require_auth`.
+    security(()),
+    responses((status = OK, description = "Host is up", body = Health))
+)]
+pub(crate) async fn get_health() -> Json<Health> {
+    Json(Health {
+        status: "ok".into(),
+        version: env!("PUNKTFUNK_VERSION").into(),
+        abi_version: punktfunk_core::ABI_VERSION,
+    })
+}
+
+/// Host identity and capabilities
+#[utoipa::path(
+    get,
+    path = "/host",
+    tag = "host",
+    operation_id = "getHostInfo",
+    responses(
+        (status = OK, description = "Host identity, versions, codecs, and port map", body = HostInfo),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn get_host_info(State(st): State<Arc<MgmtState>>) -> Json<HostInfo> {
+    let h = &st.app.host;
+    Json(HostInfo {
+        hostname: h.hostname.clone(),
+        uniqueid: h.uniqueid.clone(),
+        local_ip: h.local_ip.to_string(),
+        version: env!("PUNKTFUNK_VERSION").into(),
+        abi_version: punktfunk_core::ABI_VERSION,
+        app_version: APP_VERSION.into(),
+        gfe_version: GFE_VERSION.into(),
+        // What this host can ACTUALLY encode on its resolved backend — GPU-aware, straight from the
+        // same capability mask that drives GameStream/QUIC negotiation ([`Codec::host_wire_caps`]).
+        // So an iGPU without AV1 encode won't advertise AV1, a software-only host reports H.264 only,
+        // and PyroWave appears only when its opt-in feature is built and the backend can open.
+        codecs: {
+            let caps = Codec::host_wire_caps();
+            use punktfunk_core::quic::{CODEC_AV1, CODEC_H264, CODEC_HEVC, CODEC_PYROWAVE};
+            [
+                (CODEC_H264, ApiCodec::H264),
+                (CODEC_HEVC, ApiCodec::H265),
+                (CODEC_AV1, ApiCodec::Av1),
+                (CODEC_PYROWAVE, ApiCodec::PyroWave),
+            ]
+            .into_iter()
+            .filter(|(bit, _)| caps & bit != 0)
+            .map(|(_, codec)| codec)
+            .collect()
+        },
+        gamestream: st.gamestream_enabled,
+        ports: PortMap {
+            mgmt: st.port,
+            http: h.http_port,
+            https: h.https_port,
+            rtsp: RTSP_PORT,
+            video: VIDEO_PORT,
+            control: CONTROL_PORT,
+            audio: AUDIO_PORT,
+        },
+    })
+}
+
+/// A compositor backend the host can drive a virtual output on, and whether it's usable now.
+#[derive(Serialize, ToSchema)]
+pub(crate) struct AvailableCompositor {
+    /// Stable identifier (`"kwin"` | `"wlroots"` | `"mutter"` | `"gamescope"`) — pass this to a
+    /// client's `--compositor` flag.
+    id: String,
+    /// Human-readable label for UIs.
+    label: String,
+    /// Usable on this host right now: the live session's own compositor, or gamescope wherever
+    /// its binary is installed.
+    available: bool,
+    /// True for the backend an `Auto` (unspecified) request resolves to right now.
+    default: bool,
+}
+
+/// Available compositor backends
+///
+/// Lists every backend the host knows how to drive, flags which are usable right now, and marks
+/// the one an unspecified (`Auto`) client request resolves to. Clients pass an `id` to their
+/// `--compositor` flag (or `PUNKTFUNK_COMPOSITOR_*` over the C ABI) to request it.
+#[utoipa::path(
+    get,
+    path = "/compositors",
+    tag = "host",
+    operation_id = "listCompositors",
+    responses(
+        (status = OK, description = "Compositor backends with availability + the auto-detected default", body = [AvailableCompositor]),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn list_compositors() -> Json<Vec<AvailableCompositor>> {
+    let available = crate::vdisplay::available();
+    let default = crate::vdisplay::detect().ok();
+    Json(
+        crate::vdisplay::Compositor::all()
+            .into_iter()
+            .map(|c| AvailableCompositor {
+                id: c.id().into(),
+                label: c.label().into(),
+                available: available.contains(&c),
+                default: default == Some(c),
+            })
+            .collect(),
+    )
+}
+
+/// Live host status
+#[utoipa::path(
+    get,
+    path = "/status",
+    tag = "host",
+    operation_id = "getStatus",
+    responses(
+        (status = OK, description = "Streaming/pairing state and the active session, if any", body = RuntimeStatus),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn get_status(State(st): State<Arc<MgmtState>>) -> Json<RuntimeStatus> {
+    // GameStream plane (set by RTSP/nvhttp on the compat path).
+    let gs_launch = *st.app.launch.lock().unwrap();
+    let gs_stream = *st.app.stream.lock().unwrap();
+    let gs_video = st.app.streaming.load(Ordering::SeqCst);
+    let gs_audio = st.app.audio_streaming.load(Ordering::SeqCst);
+    // Native punktfunk/1 plane (published by the native video loop; the default plane). See
+    // [`crate::session_status`] for why this lives outside `AppState`.
+    let native = crate::session_status::snapshot();
+
+    // Detail card is singular: prefer a live GameStream session, else the first native one.
+    // `active_sessions` conveys the true count when several native clients stream at once.
+    let session = gs_launch
+        .map(|l| SessionInfo {
+            width: l.width,
+            height: l.height,
+            fps: l.fps,
+        })
+        .or_else(|| {
+            native.first().map(|s| SessionInfo {
+                width: s.width,
+                height: s.height,
+                fps: s.fps,
+            })
+        });
+    let stream = gs_stream
+        .map(|c| StreamInfo {
+            width: c.width,
+            height: c.height,
+            fps: c.fps,
+            bitrate_kbps: c.bitrate_kbps,
+            packet_size: c.packet_size as u32,
+            min_fec: c.min_fec,
+            codec: c.codec.into(),
+        })
+        .or_else(|| {
+            native.first().map(|s| StreamInfo {
+                width: s.width,
+                height: s.height,
+                fps: s.fps,
+                bitrate_kbps: s.bitrate_kbps,
+                // FEC/packetization are RTSP-negotiated (GameStream only); the native QUIC plane
+                // shards differently, so these are 0 (not applicable) for a native session.
+                packet_size: 0,
+                min_fec: 0,
+                codec: s.codec.into(),
+            })
+        });
+    Json(RuntimeStatus {
+        video_streaming: gs_video || !native.is_empty(),
+        audio_streaming: gs_audio || !native.is_empty(),
+        pin_pending: st.app.pairing.pin.awaiting_pin(),
+        paired_clients: st.app.paired.lock().unwrap().len() as u32,
+        active_sessions: native.len() as u32 + u32::from(gs_video),
+        session,
+        stream,
+    })
+}
+
+/// Local status summary for the tray icon
+///
+/// Non-sensitive status (counts and booleans only — no PIN values, no fingerprints, no device
+/// names). Unauthenticated, but served to loopback peers only.
+#[utoipa::path(
+    get,
+    path = "/local/summary",
+    tag = "host",
+    operation_id = "getLocalSummary",
+    // Override the document-global bearerAuth: loopback peers are exempt in `require_auth`.
+    security(()),
+    responses(
+        (status = OK, description = "Non-sensitive local host status (loopback peers only)", body = LocalSummary),
+        (status = UNAUTHORIZED, description = "Non-loopback peer", body = ApiError),
+    )
+)]
+pub(crate) async fn get_local_summary(State(st): State<Arc<MgmtState>>) -> Json<LocalSummary> {
+    // GameStream launch, else the first live native session — so the tray reflects a native session
+    // too (same GameStream-only blind spot the Dashboard `/status` had; see `session_status`).
+    let session = st
+        .app
+        .launch
+        .lock()
+        .unwrap()
+        .map(|l| SessionInfo {
+            width: l.width,
+            height: l.height,
+            fps: l.fps,
+        })
+        .or_else(|| {
+            crate::session_status::snapshot()
+                .first()
+                .map(|s| SessionInfo {
+                    width: s.width,
+                    height: s.height,
+                    fps: s.fps,
+                })
+        });
+    let (native_paired_clients, pending_approvals) = st
+        .native
+        .as_ref()
+        .map(|n| (n.status().paired_clients, n.pending().len() as u32))
+        .unwrap_or((0, 0));
+    Json(LocalSummary {
+        version: env!("PUNKTFUNK_VERSION").into(),
+        video_streaming: st.app.streaming.load(Ordering::SeqCst),
+        audio_streaming: st.app.audio_streaming.load(Ordering::SeqCst),
+        session,
+        paired_clients: st.app.paired.lock().unwrap().len() as u32,
+        native_paired_clients,
+        pin_pending: st.app.pairing.pin.awaiting_pin(),
+        pending_approvals,
+        kept_displays: crate::vdisplay::registry::snapshot()
+            .displays
+            .iter()
+            .filter(|d| d.state == "lingering" || d.state == "pinned")
+            .count() as u32,
+        // Cached at `serve` startup (empty when nothing was detected / never scanned) — no per-poll
+        // process enumeration.
+        conflicts: crate::detect::summary_labels(crate::detect::snapshot()),
+    })
+}

crates/punktfunk-host/src/mgmt/library.rs

@@ -0,0 +1,144 @@
+//! Library-tagged management endpoints: installed-store + custom game entries and box art.
+//! Split out of the `mgmt` facade (plan §W5).
+
+use super::shared::*;
+use axum::http::header;
+
+/// List the game library
+///
+/// Every installed-store title (Steam, read from the host's local files — no Steam API key)
+/// merged with the user's custom entries, sorted by title. Artwork fields are URLs the client
+/// fetches directly (the public Steam CDN for Steam titles).
+#[utoipa::path(
+    get,
+    path = "/library",
+    tag = "library",
+    operation_id = "getLibrary",
+    responses(
+        (status = OK, description = "Unified library across all stores", body = [crate::library::GameEntry]),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn get_library() -> Json<Vec<crate::library::GameEntry>> {
+    Json(crate::library::all_games())
+}
+
+/// Add a custom library entry
+///
+/// Creates a user-curated title (e.g. a non-Steam game, an emulator, a ROM) with caller-supplied
+/// artwork URLs. The host assigns a stable id, returned in the body.
+#[utoipa::path(
+    post,
+    path = "/library/custom",
+    tag = "library",
+    operation_id = "createCustomGame",
+    request_body = crate::library::CustomInput,
+    responses(
+        (status = CREATED, description = "Entry created", body = crate::library::CustomEntry),
+        (status = BAD_REQUEST, description = "Empty title", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+        (status = INTERNAL_SERVER_ERROR, description = "Could not persist the catalog", body = ApiError),
+    )
+)]
+pub(crate) async fn create_custom_game(
+    ApiJson(input): ApiJson<crate::library::CustomInput>,
+) -> Response {
+    if input.title.trim().is_empty() {
+        return api_error(StatusCode::BAD_REQUEST, "title must not be empty");
+    }
+    match crate::library::add_custom(input) {
+        Ok(entry) => (StatusCode::CREATED, Json(entry)).into_response(),
+        Err(e) => api_error(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string()),
+    }
+}
+
+/// Update a custom library entry
+#[utoipa::path(
+    put,
+    path = "/library/custom/{id}",
+    tag = "library",
+    operation_id = "updateCustomGame",
+    params(("id" = String, Path, description = "The custom entry id (without the `custom:` prefix)")),
+    request_body = crate::library::CustomInput,
+    responses(
+        (status = OK, description = "Entry updated", body = crate::library::CustomEntry),
+        (status = BAD_REQUEST, description = "Empty title", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+        (status = NOT_FOUND, description = "No custom entry with that id", body = ApiError),
+        (status = INTERNAL_SERVER_ERROR, description = "Could not persist the catalog", body = ApiError),
+    )
+)]
+pub(crate) async fn update_custom_game(
+    Path(id): Path<String>,
+    ApiJson(input): ApiJson<crate::library::CustomInput>,
+) -> Response {
+    if input.title.trim().is_empty() {
+        return api_error(StatusCode::BAD_REQUEST, "title must not be empty");
+    }
+    match crate::library::update_custom(&id, input) {
+        Ok(Some(entry)) => Json(entry).into_response(),
+        Ok(None) => api_error(StatusCode::NOT_FOUND, "no custom entry with that id"),
+        Err(e) => api_error(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string()),
+    }
+}
+
+/// Delete a custom library entry
+#[utoipa::path(
+    delete,
+    path = "/library/custom/{id}",
+    tag = "library",
+    operation_id = "deleteCustomGame",
+    params(("id" = String, Path, description = "The custom entry id (without the `custom:` prefix)")),
+    responses(
+        (status = NO_CONTENT, description = "Entry deleted"),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+        (status = NOT_FOUND, description = "No custom entry with that id", body = ApiError),
+        (status = INTERNAL_SERVER_ERROR, description = "Could not persist the catalog", body = ApiError),
+    )
+)]
+pub(crate) async fn delete_custom_game(Path(id): Path<String>) -> Response {
+    match crate::library::delete_custom(&id) {
+        Ok(true) => StatusCode::NO_CONTENT.into_response(),
+        Ok(false) => api_error(StatusCode::NOT_FOUND, "no custom entry with that id"),
+        Err(e) => api_error(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string()),
+    }
+}
+
+/// Fetch one cover-art image for a library entry
+///
+/// Resolves `kind` (`portrait` | `hero` | `logo` | `header`) for the given library id and streams
+/// the image bytes. For a Steam title, the host's own local Steam cache is tried first (exact —
+/// it's what the user's Steam client already shows for it), the public Steam CDN's flat URL
+/// convention as a fallback (newer titles' CDN assets can live at a per-asset-hash path the host
+/// can't predict, in which case this 404s and the client falls through to its next art candidate).
+/// Only Steam ids are backed today; any other store 404s.
+#[utoipa::path(
+    get,
+    path = "/library/art/{id}/{kind}",
+    tag = "library",
+    operation_id = "getLibraryArt",
+    params(
+        ("id" = String, Path, description = "The store-qualified library id, e.g. `steam:570`"),
+        ("kind" = String, Path, description = "`portrait` | `hero` | `logo` | `header`"),
+    ),
+    responses(
+        (status = OK, description = "Image bytes", content_type = "image/jpeg"),
+        (status = UNAUTHORIZED, description = "Missing or invalid credentials", body = ApiError),
+        (status = NOT_FOUND, description = "No art of that kind for that id", body = ApiError),
+    )
+)]
+pub(crate) async fn get_library_art(Path((id, kind)): Path<(String, String)>) -> Response {
+    let Some(kind) = crate::library::ArtKind::parse(&kind) else {
+        return api_error(StatusCode::NOT_FOUND, "unknown art kind");
+    };
+    let Some(appid) = id
+        .strip_prefix("steam:")
+        .and_then(|s| s.parse::<u32>().ok())
+    else {
+        return api_error(StatusCode::NOT_FOUND, "no art proxy for this store");
+    };
+    match tokio::task::spawn_blocking(move || crate::library::steam_art_bytes(appid, kind)).await {
+        Ok(Some((bytes, ctype))) => ([(header::CONTENT_TYPE, ctype)], bytes).into_response(),
+        _ => api_error(StatusCode::NOT_FOUND, "no art of that kind for this title"),
+    }
+}

crates/punktfunk-host/src/mgmt/native.rs

@@ -0,0 +1,361 @@
+//! Native (punktfunk/1) pairing endpoints: arm/disarm a window, paired-device management, and
+//! delegated approval of pending knocks. Split out of the `mgmt` facade (plan §W5).
+
+use super::shared::*;
+
+/// Native (punktfunk/1) pairing status. Unlike GameStream, the **host** mints the PIN (the SPAKE2
+/// ceremony needs it client-side first), so the console **displays** `pin` for the user to enter on
+/// their device — armed on demand for a short window.
+#[derive(Serialize, ToSchema)]
+pub(crate) struct NativePairStatus {
+    /// Whether the native host is running (the unified host started with `--native`).
+    enabled: bool,
+    /// True while a pairing window is open.
+    armed: bool,
+    /// The PIN to display while armed (null when disarmed).
+    #[schema(example = "1234")]
+    pin: Option<String>,
+    /// Seconds left in the window (null = disarmed, or armed with no expiry via the CLI flag).
+    expires_in_secs: Option<u64>,
+    /// Number of paired native clients.
+    paired_clients: u32,
+}
+
+/// Arm-native-pairing request body.
+#[derive(Deserialize, ToSchema)]
+pub(crate) struct ArmNativePairing {
+    /// Window length in seconds (default 120; clamped to 15–600).
+    #[schema(example = 120)]
+    ttl_secs: Option<u32>,
+    /// Optional: bind the window to ONE device fingerprint (hex SHA-256, e.g. from a pending knock).
+    /// When set, only a pairing attempt from that fingerprint consumes the window — so an unpaired
+    /// LAN peer can neither pair nor burn a window armed for a specific device (security-review #9).
+    /// Omit for an unbound window (any device may use the PIN — trusted-LAN only).
+    #[schema(example = "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08")]
+    fingerprint: Option<String>,
+}
+
+/// A paired native (punktfunk/1) client.
+#[derive(Serialize, ToSchema)]
+pub(crate) struct NativeClient {
+    /// The name the client supplied when pairing.
+    #[schema(example = "Living Room iPad")]
+    name: String,
+    /// Hex SHA-256 of the client certificate — its stable id here.
+    fingerprint: String,
+}
+
+/// An unpaired device that tried to connect while the host requires pairing — awaiting
+/// **delegated approval** (approve it here instead of fetching the host PIN out of band).
+#[derive(Serialize, ToSchema)]
+pub(crate) struct PendingDevice {
+    /// Id to address approve/deny (per-process; entries expire after ~10 minutes).
+    id: u32,
+    /// Best-effort device label (the client's own name, else fingerprint-derived).
+    #[schema(example = "Enrico's MacBook")]
+    name: String,
+    /// Hex SHA-256 of the device's certificate — what approval pins.
+    fingerprint: String,
+    /// Seconds since the device last knocked.
+    age_secs: u64,
+}
+
+/// Approve-pending-device request body. Send `{}` to keep the device's own name.
+#[derive(Deserialize, ToSchema)]
+pub(crate) struct ApprovePending {
+    /// Operator-chosen label for the device (defaults to the name it knocked with).
+    #[schema(example = "Living Room TV")]
+    name: Option<String>,
+}
+
+pub(crate) fn native_status(st: &MgmtState) -> NativePairStatus {
+    match &st.native {
+        Some(np) => {
+            let s = np.status();
+            NativePairStatus {
+                enabled: true,
+                armed: s.armed,
+                pin: s.pin,
+                expires_in_secs: s.expires_in_secs,
+                paired_clients: s.paired_clients,
+            }
+        }
+        None => NativePairStatus {
+            enabled: false,
+            armed: false,
+            pin: None,
+            expires_in_secs: None,
+            paired_clients: 0,
+        },
+    }
+}
+
+/// Native pairing status
+///
+/// The native (punktfunk/1) pairing window. Poll while armed to show the PIN + countdown.
+/// `enabled: false` means this host runs GameStream only (no `--native`).
+#[utoipa::path(
+    get,
+    path = "/native/pair",
+    tag = "native",
+    operation_id = "getNativePairing",
+    responses(
+        (status = OK, description = "Native pairing status", body = NativePairStatus),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn get_native_pairing(State(st): State<Arc<MgmtState>>) -> Json<NativePairStatus> {
+    Json(native_status(&st))
+}
+
+/// Arm native pairing
+///
+/// Opens a pairing window and mints a fresh PIN to display. The user enters it on their device
+/// within `ttl_secs`; the device then appears in the native client list.
+#[utoipa::path(
+    post,
+    path = "/native/pair/arm",
+    tag = "native",
+    operation_id = "armNativePairing",
+    request_body = ArmNativePairing,
+    responses(
+        (status = OK, description = "Pairing armed; the response carries the PIN to display", body = NativePairStatus),
+        (status = SERVICE_UNAVAILABLE, description = "Native host not available in this process", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn arm_native_pairing(
+    State(st): State<Arc<MgmtState>>,
+    ApiJson(req): ApiJson<ArmNativePairing>,
+) -> Response {
+    let Some(np) = &st.native else {
+        return api_error(
+            StatusCode::SERVICE_UNAVAILABLE,
+            "native host not available in this process",
+        );
+    };
+    let ttl = req.ttl_secs.unwrap_or(120).clamp(15, 600);
+    // A bound window (operator selected a specific device) is DoS-proof: only that fingerprint can
+    // consume it (#9). An unbound window (no fingerprint) keeps the legacy any-device behavior.
+    let bound = req
+        .fingerprint
+        .as_deref()
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+        .map(|s| s.to_ascii_lowercase());
+    let bound_to_device = bound.is_some();
+    let _pin = np.arm_for(std::time::Duration::from_secs(ttl as u64), bound);
+    tracing::info!(
+        ttl_secs = ttl,
+        bound_to_device,
+        "management API: native pairing armed"
+    );
+    Json(native_status(&st)).into_response()
+}
+
+/// Disarm native pairing
+///
+/// Closes the pairing window immediately (no new ceremonies accepted).
+#[utoipa::path(
+    delete,
+    path = "/native/pair",
+    tag = "native",
+    operation_id = "disarmNativePairing",
+    responses(
+        (status = NO_CONTENT, description = "Pairing disarmed"),
+        (status = SERVICE_UNAVAILABLE, description = "Native host not enabled", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn disarm_native_pairing(State(st): State<Arc<MgmtState>>) -> Response {
+    let Some(np) = &st.native else {
+        return api_error(StatusCode::SERVICE_UNAVAILABLE, "native host not enabled");
+    };
+    np.disarm();
+    StatusCode::NO_CONTENT.into_response()
+}
+
+/// List native paired clients
+#[utoipa::path(
+    get,
+    path = "/native/clients",
+    tag = "native",
+    operation_id = "listNativeClients",
+    responses(
+        (status = OK, description = "Paired native clients", body = [NativeClient]),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn list_native_clients(
+    State(st): State<Arc<MgmtState>>,
+) -> Json<Vec<NativeClient>> {
+    let clients = match &st.native {
+        Some(np) => np
+            .list()
+            .into_iter()
+            .map(|c| NativeClient {
+                name: c.name,
+                fingerprint: c.fingerprint,
+            })
+            .collect(),
+        None => Vec::new(),
+    };
+    Json(clients)
+}
+
+/// Unpair a native client
+///
+/// Removes a punktfunk/1 client from the native trust store by fingerprint.
+#[utoipa::path(
+    delete,
+    path = "/native/clients/{fingerprint}",
+    tag = "native",
+    operation_id = "unpairNativeClient",
+    params(
+        ("fingerprint" = String, Path,
+         description = "Hex SHA-256 of the client certificate (case-insensitive)")
+    ),
+    responses(
+        (status = NO_CONTENT, description = "Client unpaired"),
+        (status = SERVICE_UNAVAILABLE, description = "Native host not enabled", body = ApiError),
+        (status = NOT_FOUND, description = "No paired native client with that fingerprint", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn unpair_native_client(
+    State(st): State<Arc<MgmtState>>,
+    Path(fingerprint): Path<String>,
+) -> Response {
+    let Some(np) = &st.native else {
+        return api_error(StatusCode::SERVICE_UNAVAILABLE, "native host not enabled");
+    };
+    match np.remove(&fingerprint) {
+        Ok(true) => {
+            tracing::info!(fingerprint, "management API: native client unpaired");
+            StatusCode::NO_CONTENT.into_response()
+        }
+        Ok(false) => api_error(
+            StatusCode::NOT_FOUND,
+            "no paired native client with that fingerprint",
+        ),
+        Err(e) => api_error(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            &format!("could not persist trust store: {e}"),
+        ),
+    }
+}
+
+/// List devices awaiting pairing approval
+///
+/// Unpaired devices that tried to connect while the host requires pairing. Approve one to pair
+/// it without a PIN (delegated approval); entries expire after ~10 minutes.
+#[utoipa::path(
+    get,
+    path = "/native/pending",
+    tag = "native",
+    operation_id = "listPendingDevices",
+    responses(
+        (status = OK, description = "Devices awaiting approval (empty when none, or when the \
+                                     native host is not enabled)", body = Vec<PendingDevice>),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn list_pending_devices(
+    State(st): State<Arc<MgmtState>>,
+) -> Json<Vec<PendingDevice>> {
+    let pending = st
+        .native
+        .as_ref()
+        .map(|np| np.pending())
+        .unwrap_or_default();
+    Json(
+        pending
+            .into_iter()
+            .map(|p| PendingDevice {
+                id: p.id,
+                name: p.name,
+                fingerprint: p.fingerprint,
+                age_secs: p.age_secs,
+            })
+            .collect(),
+    )
+}
+
+/// Approve a pending device
+///
+/// Pairs the device's certificate fingerprint — it can connect immediately (no PIN). Optionally
+/// relabel it via the body; send `{}` to keep the name it knocked with.
+#[utoipa::path(
+    post,
+    path = "/native/pending/{id}/approve",
+    tag = "native",
+    operation_id = "approvePendingDevice",
+    params(("id" = u32, Path, description = "Pending-request id from the pending list")),
+    request_body = ApprovePending,
+    responses(
+        (status = OK, description = "Device paired", body = NativeClient),
+        (status = NOT_FOUND, description = "No pending request with that id (expired?)", body = ApiError),
+        (status = SERVICE_UNAVAILABLE, description = "Native host not enabled", body = ApiError),
+        (status = INTERNAL_SERVER_ERROR, description = "Could not persist the trust store", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn approve_pending_device(
+    State(st): State<Arc<MgmtState>>,
+    Path(id): Path<u32>,
+    ApiJson(req): ApiJson<ApprovePending>,
+) -> Response {
+    let Some(np) = &st.native else {
+        return api_error(StatusCode::SERVICE_UNAVAILABLE, "native host not enabled");
+    };
+    match np.approve_pending(id, req.name.as_deref()) {
+        Ok(Some(client)) => {
+            tracing::info!(name = %client.name, fingerprint = %client.fingerprint,
+                "management API: pending device approved (delegated pairing)");
+            Json(NativeClient {
+                name: client.name,
+                fingerprint: client.fingerprint,
+            })
+            .into_response()
+        }
+        Ok(None) => api_error(
+            StatusCode::NOT_FOUND,
+            "no pending request with that id (it may have expired — have the device retry)",
+        ),
+        Err(e) => api_error(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            &format!("could not persist trust store: {e}"),
+        ),
+    }
+}
+
+/// Deny a pending device
+///
+/// Drops the request. Not a blocklist — the device's next attempt knocks again.
+#[utoipa::path(
+    post,
+    path = "/native/pending/{id}/deny",
+    tag = "native",
+    operation_id = "denyPendingDevice",
+    params(("id" = u32, Path, description = "Pending-request id from the pending list")),
+    responses(
+        (status = NO_CONTENT, description = "Request dropped"),
+        (status = NOT_FOUND, description = "No pending request with that id", body = ApiError),
+        (status = SERVICE_UNAVAILABLE, description = "Native host not enabled", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn deny_pending_device(
+    State(st): State<Arc<MgmtState>>,
+    Path(id): Path<u32>,
+) -> Response {
+    let Some(np) = &st.native else {
+        return api_error(StatusCode::SERVICE_UNAVAILABLE, "native host not enabled");
+    };
+    if np.deny_pending(id) {
+        tracing::info!(id, "management API: pending device denied");
+        StatusCode::NO_CONTENT.into_response()
+    } else {
+        api_error(StatusCode::NOT_FOUND, "no pending request with that id")
+    }
+}

crates/punktfunk-host/src/mgmt/session.rs

@@ -0,0 +1,65 @@
+//! Session-tagged management endpoints: stop the active session, force an IDR. Split out of the
+//! `mgmt` facade (plan §W5).
+
+use super::shared::*;
+use std::sync::atomic::Ordering;
+
+/// Stop the active session
+///
+/// Kicks the connected client: stops the video/audio stream threads and clears the launch
+/// state. Idempotent — succeeds even when nothing is streaming.
+#[utoipa::path(
+    delete,
+    path = "/session",
+    tag = "session",
+    operation_id = "stopSession",
+    responses(
+        (status = NO_CONTENT, description = "Session stopped (or none was active)"),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn stop_session(State(st): State<Arc<MgmtState>>) -> StatusCode {
+    let was_streaming = st.app.streaming.swap(false, Ordering::SeqCst);
+    st.app.audio_streaming.store(false, Ordering::SeqCst);
+    *st.app.launch.lock().unwrap() = None;
+    *st.app.stream.lock().unwrap() = None;
+    // Native plane: the GameStream flags above don't reach it (it runs its own loops off the shared
+    // session registry), so signal every live native session to tear down too.
+    let native = crate::session_status::count();
+    crate::session_status::stop_all();
+    tracing::info!(
+        was_streaming,
+        native_sessions = native,
+        "management API: session stopped"
+    );
+    StatusCode::NO_CONTENT
+}
+
+/// Force a keyframe
+///
+/// Asks the encoder for an IDR frame on the active video stream (what a client requests
+/// after unrecoverable loss — exposed for debugging).
+#[utoipa::path(
+    post,
+    path = "/session/idr",
+    tag = "session",
+    operation_id = "requestIdr",
+    responses(
+        (status = ACCEPTED, description = "Keyframe requested"),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+        (status = CONFLICT, description = "No active video stream", body = ApiError),
+    )
+)]
+pub(crate) async fn request_idr(State(st): State<Arc<MgmtState>>) -> Response {
+    let gs = st.app.streaming.load(Ordering::SeqCst);
+    let native = crate::session_status::count();
+    if !gs && native == 0 {
+        return api_error(StatusCode::CONFLICT, "no active video stream");
+    }
+    if gs {
+        st.app.force_idr.store(true, Ordering::SeqCst);
+    }
+    // Native sessions get the keyframe request through their registry flag (see `session_status`).
+    crate::session_status::force_idr_all();
+    StatusCode::ACCEPTED.into_response()
+}

crates/punktfunk-host/src/mgmt/shared.rs

@@ -0,0 +1,51 @@
+//! Shared control-plane plumbing for the management submodules: the [`ApiError`] envelope
+//! every non-2xx response wears, [`api_error`], the [`ApiJson`] extractor that keeps axum's own
+//! rejections in that envelope, and a small re-export prelude of the axum/serde/utoipa vocabulary
+//! the handler modules share. Split out of the `mgmt` facade (plan §W5).
+
+use axum::extract::Request;
+
+// Re-export prelude: the vocabulary every handler submodule pulls in via `use super::shared::*`.
+pub(crate) use super::MgmtState;
+pub(crate) use axum::extract::{Path, Query, State};
+pub(crate) use axum::http::StatusCode;
+pub(crate) use axum::response::{IntoResponse, Response};
+pub(crate) use axum::Json;
+pub(crate) use serde::{Deserialize, Serialize};
+pub(crate) use std::sync::Arc;
+pub(crate) use utoipa::ToSchema;
+
+/// Error envelope for every non-2xx response.
+#[derive(Serialize, Deserialize, ToSchema)]
+pub(crate) struct ApiError {
+    error: String,
+}
+
+pub(crate) fn api_error(status: StatusCode, message: &str) -> Response {
+    (
+        status,
+        Json(ApiError {
+            error: message.to_string(),
+        }),
+    )
+        .into_response()
+}
+
+/// `axum::Json` whose rejections (bad JSON → 400/422, wrong content-type → 415) are
+/// rewrapped in the [`ApiError`] envelope, keeping "every non-2xx body is `ApiError`" true.
+pub(crate) struct ApiJson<T>(pub(crate) T);
+
+impl<S, T> axum::extract::FromRequest<S> for ApiJson<T>
+where
+    Json<T>: axum::extract::FromRequest<S, Rejection = axum::extract::rejection::JsonRejection>,
+    S: Send + Sync,
+{
+    type Rejection = Response;
+
+    async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> {
+        match Json::<T>::from_request(req, state).await {
+            Ok(Json(value)) => Ok(ApiJson(value)),
+            Err(rejection) => Err(api_error(rejection.status(), &rejection.body_text())),
+        }
+    }
+}

crates/punktfunk-host/src/mgmt/stats.rs

@@ -0,0 +1,221 @@
+//! Stats/logs-tagged management endpoints: performance-capture control + time-series and the
+//! in-memory log stream. Split out of the `mgmt` facade (plan §W5).
+
+use super::shared::*;
+use crate::log_capture::LogPage;
+use crate::stats_recorder::Capture;
+use crate::stats_recorder::CaptureMeta;
+use crate::stats_recorder::StatsStatus;
+
+/// Start a stats capture
+///
+/// Arms a new performance-stats capture. Idempotent: if a capture is already running this returns
+/// the current status unchanged. While armed, the streaming loops emit aggregated samples (~ every
+/// 1–2 s) into the in-progress capture, readable live via `GET /stats/capture/live`.
+#[utoipa::path(
+    post,
+    path = "/stats/capture/start",
+    tag = "stats",
+    operation_id = "statsCaptureStart",
+    responses(
+        (status = OK, description = "Capture armed (or already running)", body = StatsStatus),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn stats_capture_start(State(st): State<Arc<MgmtState>>) -> Json<StatsStatus> {
+    let status = st.stats.start();
+    tracing::info!(
+        started_unix_ms = status.started_unix_ms,
+        "management API: stats capture armed"
+    );
+    Json(status)
+}
+
+/// Stop the stats capture
+///
+/// Disarms the in-progress capture and writes it to disk atomically, returning its summary. If
+/// nothing was recording, returns `204 No Content`.
+#[utoipa::path(
+    post,
+    path = "/stats/capture/stop",
+    tag = "stats",
+    operation_id = "statsCaptureStop",
+    responses(
+        (status = OK, description = "Capture stopped and saved", body = CaptureMeta),
+        (status = NO_CONTENT, description = "Nothing was recording"),
+        (status = INTERNAL_SERVER_ERROR, description = "Could not write the recording to disk", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn stats_capture_stop(State(st): State<Arc<MgmtState>>) -> Response {
+    match st.stats.stop() {
+        Ok(Some(meta)) => {
+            tracing::info!(id = %meta.id, samples = meta.sample_count, "management API: stats capture saved");
+            (StatusCode::OK, Json(meta)).into_response()
+        }
+        Ok(None) => StatusCode::NO_CONTENT.into_response(),
+        Err(e) => api_error(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            &format!("could not save capture: {e}"),
+        ),
+    }
+}
+
+/// Stats capture status
+///
+/// Whether a capture is armed, its sample count, and start time. Poll this (e.g. every 2 s) to
+/// drive the capture-control UI.
+#[utoipa::path(
+    get,
+    path = "/stats/capture/status",
+    tag = "stats",
+    operation_id = "statsCaptureStatus",
+    responses(
+        (status = OK, description = "In-progress capture status (idle when not armed)", body = StatsStatus),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn stats_capture_status(State(st): State<Arc<MgmtState>>) -> Json<StatsStatus> {
+    Json(st.stats.status())
+}
+
+/// Live in-progress capture
+///
+/// The full sample time-series of the capture currently recording, for live graphing. `404` when
+/// nothing is armed.
+#[utoipa::path(
+    get,
+    path = "/stats/capture/live",
+    tag = "stats",
+    operation_id = "statsCaptureLive",
+    responses(
+        (status = OK, description = "The in-progress capture (meta + samples so far)", body = Capture),
+        (status = NOT_FOUND, description = "No capture is currently recording", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn stats_capture_live(State(st): State<Arc<MgmtState>>) -> Response {
+    match st.stats.live_snapshot() {
+        Some(capture) => Json(capture).into_response(),
+        None => api_error(StatusCode::NOT_FOUND, "no capture is currently recording"),
+    }
+}
+
+/// List saved recordings
+///
+/// Every saved capture's summary (the `meta` head only — not the sample body), newest first.
+#[utoipa::path(
+    get,
+    path = "/stats/recordings",
+    tag = "stats",
+    operation_id = "statsRecordingsList",
+    responses(
+        (status = OK, description = "Saved capture summaries, newest first", body = [CaptureMeta]),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn stats_recordings_list(
+    State(st): State<Arc<MgmtState>>,
+) -> Json<Vec<CaptureMeta>> {
+    Json(st.stats.list())
+}
+
+/// Get a saved recording
+///
+/// The full capture (meta + samples) for `id`, for graphing or download.
+#[utoipa::path(
+    get,
+    path = "/stats/recordings/{id}",
+    tag = "stats",
+    operation_id = "statsRecordingGet",
+    params(("id" = String, Path, description = "The recording id (its filename stem)")),
+    responses(
+        (status = OK, description = "The full capture", body = Capture),
+        (status = NOT_FOUND, description = "No recording with that id", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+        (status = INTERNAL_SERVER_ERROR, description = "The recording file is unreadable", body = ApiError),
+    )
+)]
+pub(crate) async fn stats_recording_get(
+    State(st): State<Arc<MgmtState>>,
+    Path(id): Path<String>,
+) -> Response {
+    match st.stats.load(&id) {
+        Ok(capture) => Json(capture).into_response(),
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
+            api_error(StatusCode::NOT_FOUND, "no recording with that id")
+        }
+        Err(e) => api_error(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            &format!("could not read recording: {e}"),
+        ),
+    }
+}
+
+/// Delete a saved recording
+///
+/// Removes the recording `id` from disk. `404` if there is no such recording.
+#[utoipa::path(
+    delete,
+    path = "/stats/recordings/{id}",
+    tag = "stats",
+    operation_id = "statsRecordingDelete",
+    params(("id" = String, Path, description = "The recording id (its filename stem)")),
+    responses(
+        (status = NO_CONTENT, description = "Recording deleted"),
+        (status = NOT_FOUND, description = "No recording with that id", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+        (status = INTERNAL_SERVER_ERROR, description = "Could not delete the recording", body = ApiError),
+    )
+)]
+pub(crate) async fn stats_recording_delete(
+    State(st): State<Arc<MgmtState>>,
+    Path(id): Path<String>,
+) -> Response {
+    match st.stats.delete(&id) {
+        Ok(()) => {
+            tracing::info!(id, "management API: recording deleted");
+            StatusCode::NO_CONTENT.into_response()
+        }
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
+            api_error(StatusCode::NOT_FOUND, "no recording with that id")
+        }
+        Err(e) => api_error(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            &format!("could not delete recording: {e}"),
+        ),
+    }
+}
+
+/// Query for `GET /logs` — a cursor poll.
+#[derive(Deserialize)]
+pub(crate) struct LogsQuery {
+    after: Option<u64>,
+    limit: Option<u32>,
+}
+
+/// Host logs
+///
+/// The host's recent log entries — an in-memory ring of the newest few thousand, captured at
+/// DEBUG and above regardless of `RUST_LOG`. Follow live by polling with `after` set to the last
+/// response's `next` cursor; a `dropped: true` means entries were evicted between polls (the ring
+/// wrapped). Bearer-only: logs can reference client identities and host paths, so this is part of
+/// the loopback-only admin surface, never the LAN-readable mTLS one.
+#[utoipa::path(
+    get,
+    path = "/logs",
+    tag = "logs",
+    operation_id = "logsGet",
+    params(
+        ("after" = Option<u64>, Query, description = "Return entries with seq greater than this (omitted/0 = oldest retained)"),
+        ("limit" = Option<u32>, Query, description = "Max entries per response (default and cap 1000)"),
+    ),
+    responses(
+        (status = OK, description = "Entries after the cursor, oldest first", body = LogPage),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn logs_get(Query(q): Query<LogsQuery>) -> Json<LogPage> {
+    let limit = q.limit.map_or(crate::log_capture::MAX_PAGE, |l| l as usize);
+    Json(crate::log_capture::ring().since(q.after.unwrap_or(0), limit))
+}

crates/punktfunk-host/src/mgmt/tests.rs

@@ -0,0 +1,948 @@
+//! Handler + auth tests for the management API, exercised through `app()`. Split out of the
+//! `mgmt` facade (plan §W5).
+
+use super::*;
+use crate::encode::Codec;
+use crate::gamestream::tls::{PeerAddr, PeerCertFingerprint};
+use crate::gamestream::{cert::ServerIdentity, Host, LaunchSession, HTTPS_PORT, HTTP_PORT};
+use axum::body::Body;
+use axum::http::StatusCode;
+use http_body_util::BodyExt;
+use sha2::{Digest, Sha256};
+use std::net::{IpAddr, Ipv4Addr};
+use std::sync::atomic::Ordering;
+use tower::ServiceExt;
+
+/// A throwaway stats recorder rooted in a unique temp dir (never touches the real config dir).
+fn test_stats() -> Arc<crate::stats_recorder::StatsRecorder> {
+    crate::stats_recorder::StatsRecorder::new(std::env::temp_dir().join(format!(
+        "pf-mgmt-stats-{}-{:p}",
+        std::process::id(),
+        &0u8 as *const u8
+    )))
+}
+
+fn test_state() -> Arc<AppState> {
+    let host = Host {
+        hostname: "test-host".into(),
+        uniqueid: "deadbeef".into(),
+        local_ip: IpAddr::V4(Ipv4Addr::LOCALHOST),
+        http_port: HTTP_PORT,
+        https_port: HTTPS_PORT,
+    };
+    let identity = ServerIdentity::ephemeral().expect("ephemeral identity");
+    Arc::new(AppState::new(host, identity, test_stats()))
+}
+
+// The mgmt API now always requires auth, so the router always has a token. A test that passes
+// `None` gets the default "test-secret" (and `send` auto-attaches the matching bearer); a test
+// that passes an explicit token exercises a mismatch (e.g. `bearer_token_is_enforced`).
+fn test_app(state: Arc<AppState>, token: Option<&str>) -> Router {
+    let stats = state.stats.clone();
+    app(
+        state,
+        Some(token.unwrap_or("test-secret").to_string()),
+        DEFAULT_PORT,
+        None,
+        stats,
+        // GameStream-compat planes off (the secure default the native-only tests model).
+        false,
+    )
+}
+
+fn test_app_native(state: Arc<AppState>, np: Arc<crate::native_pairing::NativePairing>) -> Router {
+    // Auth required always; the paired-cert tests inject a fingerprint (cert branch wins), the
+    // rest authenticate via the `send`-attached default bearer.
+    let stats = state.stats.clone();
+    app(
+        state,
+        Some("test-secret".to_string()),
+        DEFAULT_PORT,
+        Some(np),
+        stats,
+        false,
+    )
+}
+
+async fn send(app: &Router, mut req: axum::http::Request<Body>) -> (StatusCode, serde_json::Value) {
+    // Auto-attach the default bearer unless the test set its own Authorization (e.g. the
+    // mismatch cases in `bearer_token_is_enforced`). Open routes ignore it; authed routes
+    // accept it against the `test-secret` default token.
+    if !req
+        .headers()
+        .contains_key(axum::http::header::AUTHORIZATION)
+    {
+        req.headers_mut().insert(
+            axum::http::header::AUTHORIZATION,
+            axum::http::HeaderValue::from_static("Bearer test-secret"),
+        );
+    }
+    let resp = app.clone().oneshot(req).await.expect("infallible");
+    let status = resp.status();
+    let bytes = resp.into_body().collect().await.unwrap().to_bytes();
+    let json = if bytes.is_empty() {
+        serde_json::Value::Null
+    } else {
+        serde_json::from_slice(&bytes).unwrap_or(serde_json::Value::Null)
+    };
+    (status, json)
+}
+
+fn get_req(path: &str) -> axum::http::Request<Body> {
+    axum::http::Request::get(path).body(Body::empty()).unwrap()
+}
+
+/// Send a request authenticated ONLY by a paired streaming cert (the `PeerCertFingerprint`
+/// `serve_https` would attach) — no bearer header — so `require_auth`'s cert branch decides.
+async fn send_cert(app: &Router, mut req: axum::http::Request<Body>, fp: &str) -> StatusCode {
+    req.extensions_mut()
+        .insert(PeerCertFingerprint(Some(fp.to_string())));
+    app.clone().oneshot(req).await.expect("infallible").status()
+}
+
+/// A paired *streaming* cert (mTLS, no bearer) authorizes only the read-only allowlist; every
+/// state-changing or PIN-exposing route still requires the operator's bearer token (audit #4).
+#[tokio::test]
+async fn cert_auth_is_a_read_only_allowlist() {
+    let np = Arc::new(
+        crate::native_pairing::NativePairing::load_with(
+            Some(std::env::temp_dir().join(format!("pf-mgmt-cert-{}.json", std::process::id()))),
+            None,
+            false,
+        )
+        .unwrap(),
+    );
+    let fp = "deadbeefcafe";
+    np.add("streaming-client", fp).unwrap();
+    let app = test_app_native(test_state(), np);
+
+    // Allowlisted read-only GETs → the cert authorizes them (not 401).
+    for p in [
+        "/api/v1/host",
+        "/api/v1/status",
+        "/api/v1/compositors",
+        "/api/v1/clients",
+        "/api/v1/native/clients",
+        "/api/v1/library",
+    ] {
+        assert_ne!(
+            send_cert(&app, get_req(p), fp).await,
+            StatusCode::UNAUTHORIZED,
+            "a paired streaming cert should authorize GET {p}"
+        );
+    }
+    // PIN-exposing GET + state-changing routes → token-only (cert rejected without a bearer).
+    assert_eq!(
+        send_cert(&app, get_req("/api/v1/native/pair"), fp).await,
+        StatusCode::UNAUTHORIZED,
+        "GET /native/pair exposes the PIN → must require the bearer token"
+    );
+    assert_eq!(
+        send_cert(
+            &app,
+            post_json(
+                "/api/v1/native/pair/arm",
+                serde_json::json!({"ttl_secs": 60})
+            ),
+            fp,
+        )
+        .await,
+        StatusCode::UNAUTHORIZED,
+        "arming pairing must require the bearer token"
+    );
+    assert_eq!(
+        send_cert(
+            &app,
+            axum::http::Request::delete("/api/v1/native/clients/deadbeefcafe")
+                .body(Body::empty())
+                .unwrap(),
+            fp,
+        )
+        .await,
+        StatusCode::UNAUTHORIZED,
+        "unpair (DELETE) must require the bearer token"
+    );
+    // An UNPAIRED cert is rejected even on an allowlisted path.
+    assert_eq!(
+        send_cert(&app, get_req("/api/v1/status"), "not-paired").await,
+        StatusCode::UNAUTHORIZED,
+        "an unpaired cert must be rejected"
+    );
+}
+
+/// The bearer-token (admin) path is honored only from a LOOPBACK peer: the same token from a LAN
+/// peer is rejected, so binding the listener to all interfaces (so paired clients can browse the
+/// library by default) never LAN-exposes the admin surface. A paired *cert*, by contrast, reaches
+/// the read-only allowlist from anywhere.
+#[tokio::test]
+async fn bearer_admin_is_loopback_only() {
+    let lan: SocketAddr = "192.168.1.50:54321".parse().unwrap();
+    let loopback: SocketAddr = "127.0.0.1:33333".parse().unwrap();
+    let bearer = |peer: SocketAddr| {
+        let mut req = get_req("/api/v1/stats/recordings"); // a bearer-only (admin) route
+        req.extensions_mut().insert(PeerAddr(peer));
+        req.headers_mut().insert(
+            axum::http::header::AUTHORIZATION,
+            axum::http::HeaderValue::from_static("Bearer test-secret"),
+        );
+        req
+    };
+
+    let app = test_app(test_state(), None);
+    // A valid bearer from a LAN peer → rejected on the admin API.
+    assert_eq!(
+        app.clone()
+            .oneshot(bearer(lan))
+            .await
+            .expect("infallible")
+            .status(),
+        StatusCode::UNAUTHORIZED,
+        "a bearer token from a LAN peer must be rejected on the admin API"
+    );
+    // The SAME token from a loopback peer (the web console BFF) → accepted.
+    assert_ne!(
+        app.clone()
+            .oneshot(bearer(loopback))
+            .await
+            .expect("infallible")
+            .status(),
+        StatusCode::UNAUTHORIZED,
+        "the bearer token must be accepted from a loopback peer"
+    );
+
+    // A paired cert from a LAN peer still reaches the read-only library (the feature this enables).
+    let np = Arc::new(
+        crate::native_pairing::NativePairing::load_with(
+            Some(std::env::temp_dir().join(format!("pf-mgmt-lanlib-{}.json", std::process::id()))),
+            None,
+            false,
+        )
+        .unwrap(),
+    );
+    let fp = "deadbeefcafe";
+    np.add("lan-client", fp).unwrap();
+    let app = test_app_native(test_state(), np);
+    let mut req = get_req("/api/v1/library");
+    req.extensions_mut().insert(PeerAddr(lan));
+    req.extensions_mut()
+        .insert(PeerCertFingerprint(Some(fp.to_string())));
+    assert_ne!(
+        app.clone().oneshot(req).await.expect("infallible").status(),
+        StatusCode::UNAUTHORIZED,
+        "a paired cert must reach the library from a LAN peer"
+    );
+
+    // The per-image art proxy (`/api/v1/library/art/{id}/{kind}`) is a prefix match in
+    // `cert_may_access`, not an exact one (dynamic id/kind segments) — exercise it directly. An
+    // unknown `kind` 404s before any disk/network I/O, so this stays a fast, deterministic check
+    // of the auth gate (not of art resolution, which `library::tests` covers).
+    let mut req = get_req("/api/v1/library/art/steam:570/not-a-real-kind");
+    req.extensions_mut().insert(PeerAddr(lan));
+    req.extensions_mut()
+        .insert(PeerCertFingerprint(Some(fp.to_string())));
+    assert_eq!(
+        app.clone().oneshot(req).await.expect("infallible").status(),
+        StatusCode::NOT_FOUND,
+        "a paired cert must reach the per-image library art proxy from a LAN peer \
+         (and an unknown kind 404s, rather than ever being rejected as unauthorized)"
+    );
+}
+
+#[tokio::test]
+async fn health_is_open_and_versioned() {
+    let app = test_app(test_state(), None);
+    let (status, body) = send(&app, get_req("/api/v1/health")).await;
+    assert_eq!(status, StatusCode::OK);
+    assert_eq!(body["status"], "ok");
+    assert_eq!(body["abi_version"], punktfunk_core::ABI_VERSION);
+}
+
+/// The tray's `/local/summary` is unauthenticated for LOOPBACK peers only — a LAN peer is
+/// rejected even though the route needs no bearer token, and the body never carries secret
+/// material (no PIN values, no fingerprints, no device names — counts/booleans only).
+#[tokio::test]
+async fn local_summary_is_loopback_only_and_non_sensitive() {
+    let np = Arc::new(
+        crate::native_pairing::NativePairing::load_with(
+            Some(std::env::temp_dir().join(format!("pf-mgmt-summary-{}.json", std::process::id()))),
+            None,
+            false,
+        )
+        .unwrap(),
+    );
+    np.add("secret-device-name", "deadbeefcafe0123").unwrap();
+    let app = test_app_native(test_state(), np);
+
+    // Loopback peer, NO auth header → 200 with the expected shape.
+    let mut req = get_req("/api/v1/local/summary");
+    req.extensions_mut()
+        .insert(PeerAddr("127.0.0.1:40000".parse().unwrap()));
+    let (status, body) = send(&app, req).await;
+    assert_eq!(status, StatusCode::OK);
+    assert_eq!(body["video_streaming"], false);
+    assert_eq!(body["native_paired_clients"], 1);
+    assert_eq!(body["pending_approvals"], 0);
+    assert!(body["version"].is_string());
+    // No secret material anywhere in the body (paired name / fingerprint must not leak).
+    let raw = body.to_string();
+    assert!(
+        !raw.contains("deadbeefcafe0123") && !raw.contains("secret-device-name"),
+        "summary must not leak fingerprints or device names: {raw}"
+    );
+
+    // The same request from a LAN peer → rejected (route is loopback-gated, not just tokenless).
+    let mut req = get_req("/api/v1/local/summary");
+    req.extensions_mut()
+        .insert(PeerAddr("192.168.1.50:40000".parse().unwrap()));
+    let (status, _) = send(&app, req).await;
+    assert_eq!(
+        status,
+        StatusCode::UNAUTHORIZED,
+        "the local summary must be rejected for a LAN peer"
+    );
+
+    // IPv6 loopback counts as loopback.
+    let mut req = get_req("/api/v1/local/summary");
+    req.extensions_mut()
+        .insert(PeerAddr("[::1]:40000".parse().unwrap()));
+    let (status, _) = send(&app, req).await;
+    assert_eq!(status, StatusCode::OK, "::1 is a loopback peer");
+}
+
+#[tokio::test]
+async fn bearer_token_is_enforced() {
+    let app = test_app(test_state(), Some("sekrit"));
+
+    // No/wrong token → 401 with the error envelope.
+    let (status, body) = send(&app, get_req("/api/v1/status")).await;
+    assert_eq!(status, StatusCode::UNAUTHORIZED);
+    assert!(body["error"].as_str().unwrap().contains("bearer"));
+    let wrong = axum::http::Request::get("/api/v1/status")
+        .header("authorization", "Bearer nope")
+        .body(Body::empty())
+        .unwrap();
+    assert_eq!(send(&app, wrong).await.0, StatusCode::UNAUTHORIZED);
+
+    // Right token → 200.
+    let right = axum::http::Request::get("/api/v1/status")
+        .header("authorization", "Bearer sekrit")
+        .body(Body::empty())
+        .unwrap();
+    assert_eq!(send(&app, right).await.0, StatusCode::OK);
+
+    // Health + the spec/docs stay open.
+    assert_eq!(
+        send(&app, get_req("/api/v1/health")).await.0,
+        StatusCode::OK
+    );
+    assert_eq!(
+        send(&app, get_req("/api/v1/openapi.json")).await.0,
+        StatusCode::OK
+    );
+    let docs = app.clone().oneshot(get_req("/api/docs")).await.unwrap();
+    assert_eq!(docs.status(), StatusCode::OK);
+    let html = docs.into_body().collect().await.unwrap().to_bytes();
+    assert!(
+        html.starts_with(b"<!doctype html>"),
+        "Scalar UI should serve HTML"
+    );
+}
+
+#[tokio::test]
+async fn host_info_reports_identity_and_ports() {
+    let app = test_app(test_state(), None);
+    let (status, body) = send(&app, get_req("/api/v1/host")).await;
+    assert_eq!(status, StatusCode::OK);
+    assert_eq!(body["hostname"], "test-host");
+    assert_eq!(body["uniqueid"], "deadbeef");
+    assert_eq!(body["ports"]["http"], HTTP_PORT);
+    assert_eq!(body["ports"]["mgmt"], DEFAULT_PORT);
+    // Codecs are GPU-aware (derived from `Codec::host_wire_caps`), so assert against that mask
+    // rather than a fixed set — and confirm HEVC serializes as "hevc" (the unified codec label),
+    // never "h265".
+    use punktfunk_core::quic::{CODEC_AV1, CODEC_H264, CODEC_HEVC, CODEC_PYROWAVE};
+    let caps = Codec::host_wire_caps();
+    let expected: Vec<&str> = [
+        (CODEC_H264, "h264"),
+        (CODEC_HEVC, "hevc"),
+        (CODEC_AV1, "av1"),
+        (CODEC_PYROWAVE, "pyrowave"),
+    ]
+    .into_iter()
+    .filter(|(bit, _)| caps & bit != 0)
+    .map(|(_, name)| name)
+    .collect();
+    assert_eq!(body["codecs"], serde_json::json!(expected));
+    assert!(caps & CODEC_H264 != 0, "H.264 is always encodable");
+    // test_app models the secure default (GameStream-compat off).
+    assert_eq!(body["gamestream"], false);
+}
+
+#[tokio::test]
+async fn compositors_lists_all_backends_with_flags() {
+    let app = test_app(test_state(), None);
+    let (status, body) = send(&app, get_req("/api/v1/compositors")).await;
+    assert_eq!(status, StatusCode::OK);
+    let arr = body.as_array().expect("array");
+    // Every backend the host knows, in stable order.
+    let ids: Vec<&str> = arr.iter().map(|c| c["id"].as_str().unwrap()).collect();
+    assert_eq!(ids, ["kwin", "gamescope", "mutter", "wlroots", "hyprland"]);
+    for c in arr {
+        assert!(c["available"].is_boolean());
+        assert!(c["default"].is_boolean());
+        assert!(c["label"].as_str().is_some_and(|s| !s.is_empty()));
+    }
+    // At most one backend is the auto-detect default (none, if the test env has no desktop).
+    assert!(arr.iter().filter(|c| c["default"] == true).count() <= 1);
+}
+
+#[tokio::test]
+async fn status_reflects_runtime_state() {
+    let state = test_state();
+    let app = test_app(state.clone(), None);
+
+    let (_, body) = send(&app, get_req("/api/v1/status")).await;
+    assert_eq!(body["video_streaming"], false);
+    assert_eq!(body["session"], serde_json::Value::Null);
+
+    *state.launch.lock().unwrap() = Some(LaunchSession {
+        gcm_key: [0; 16],
+        rikeyid: 1,
+        width: 2560,
+        height: 1440,
+        fps: 120,
+        appid: 1,
+        peer_ip: None,
+        owner_fp: None,
+    });
+    state.streaming.store(true, Ordering::SeqCst);
+
+    let (_, body) = send(&app, get_req("/api/v1/status")).await;
+    assert_eq!(body["video_streaming"], true);
+    assert_eq!(body["session"]["width"], 2560);
+    assert_eq!(body["session"]["fps"], 120);
+    // Key material must never appear anywhere in the response.
+    assert!(!body.to_string().contains("gcm"));
+}
+
+#[tokio::test]
+async fn paired_clients_list_and_unpair() {
+    let state = test_state();
+    let app = test_app(state.clone(), None);
+
+    // Pin the host's own cert DER as a stand-in client.
+    let (_, pem) = x509_parser::pem::parse_x509_pem(state.identity.cert_pem.as_bytes()).unwrap();
+    let der = pem.contents.clone();
+    let fingerprint = hex::encode(Sha256::digest(&der));
+    // Isolate from any real paired store on the dev box: AppState::new loads
+    // ~/.config/punktfunk/paired.json, so clear it before seeding our stand-in — otherwise
+    // a real GameStream-paired client lands at body[0] and this assertion sees its hash.
+    {
+        let mut p = state.paired.lock().unwrap();
+        p.clear();
+        p.push(der);
+    }
+
+    let (status, body) = send(&app, get_req("/api/v1/clients")).await;
+    assert_eq!(status, StatusCode::OK);
+    assert_eq!(body[0]["fingerprint"], fingerprint);
+    assert_eq!(body[0]["subject"], "CN=punktfunk");
+
+    // Malformed fingerprint → 400.
+    let bad = axum::http::Request::delete("/api/v1/clients/zz")
+        .body(Body::empty())
+        .unwrap();
+    assert_eq!(send(&app, bad).await.0, StatusCode::BAD_REQUEST);
+
+    // Unpair (uppercase hex must match too) → 204, list empties, second delete → 404.
+    let del = |fp: String| {
+        axum::http::Request::delete(format!("/api/v1/clients/{fp}"))
+            .body(Body::empty())
+            .unwrap()
+    };
+    assert_eq!(
+        send(&app, del(fingerprint.to_uppercase())).await.0,
+        StatusCode::NO_CONTENT
+    );
+    let (_, body) = send(&app, get_req("/api/v1/clients")).await;
+    assert_eq!(body, serde_json::json!([]));
+    assert_eq!(send(&app, del(fingerprint)).await.0, StatusCode::NOT_FOUND);
+}
+
+#[tokio::test]
+async fn submit_pin_validates_and_requires_pending_pairing() {
+    let app = test_app(test_state(), None);
+    let post = |body: &str| {
+        axum::http::Request::post("/api/v1/pair/pin")
+            .header("content-type", "application/json")
+            .body(Body::from(body.to_string()))
+            .unwrap()
+    };
+
+    // Malformed PINs → 400.
+    assert_eq!(
+        send(&app, post(r#"{"pin":""}"#)).await.0,
+        StatusCode::BAD_REQUEST
+    );
+    assert_eq!(
+        send(&app, post(r#"{"pin":"12ab"}"#)).await.0,
+        StatusCode::BAD_REQUEST
+    );
+
+    // Well-formed but nothing waiting → 409 (a parked stale PIN would poison the
+    // next pairing attempt).
+    assert_eq!(
+        send(&app, post(r#"{"pin":"1234"}"#)).await.0,
+        StatusCode::CONFLICT
+    );
+
+    // axum's own body rejections must still wear the ApiError envelope (ApiJson).
+    let (status, body) = send(&app, post("{not json")).await;
+    assert_eq!(status, StatusCode::BAD_REQUEST);
+    assert!(body["error"].is_string(), "syntax error: {body}");
+    let (status, body) = send(&app, post(r#"{"wrong":"shape"}"#)).await;
+    assert_eq!(status, StatusCode::UNPROCESSABLE_ENTITY);
+    assert!(body["error"].is_string(), "schema mismatch: {body}");
+    let no_ct = axum::http::Request::post("/api/v1/pair/pin")
+        .body(Body::from(r#"{"pin":"1234"}"#))
+        .unwrap();
+    let (status, body) = send(&app, no_ct).await;
+    assert_eq!(status, StatusCode::UNSUPPORTED_MEDIA_TYPE);
+    assert!(body["error"].is_string(), "media type: {body}");
+}
+
+/// A blank token is treated as no token: the mgmt API requires auth always (even on loopback),
+/// so `run` refuses to start unauthenticated rather than serve open.
+#[tokio::test]
+async fn blank_token_rejected() {
+    let opts = Options {
+        bind: "127.0.0.1:0".parse().unwrap(),
+        token: Some("   ".into()),
+    };
+    let err = run(test_state(), opts, None, test_stats(), false)
+        .await
+        .unwrap_err();
+    assert!(err.to_string().contains("no token"), "{err}");
+}
+
+#[tokio::test]
+async fn stop_session_clears_runtime_state() {
+    let state = test_state();
+    let app = test_app(state.clone(), None);
+    state.streaming.store(true, Ordering::SeqCst);
+    state.audio_streaming.store(true, Ordering::SeqCst);
+    *state.launch.lock().unwrap() = Some(LaunchSession {
+        gcm_key: [0; 16],
+        rikeyid: 0,
+        width: 1920,
+        height: 1080,
+        fps: 60,
+        appid: 1,
+        peer_ip: None,
+        owner_fp: None,
+    });
+
+    let del = axum::http::Request::delete("/api/v1/session")
+        .body(Body::empty())
+        .unwrap();
+    assert_eq!(send(&app, del).await.0, StatusCode::NO_CONTENT);
+    assert!(!state.streaming.load(Ordering::SeqCst));
+    assert!(!state.audio_streaming.load(Ordering::SeqCst));
+    assert!(state.launch.lock().unwrap().is_none());
+}
+
+#[tokio::test]
+async fn idr_requires_an_active_stream() {
+    let state = test_state();
+    let app = test_app(state.clone(), None);
+    let post = || {
+        axum::http::Request::post("/api/v1/session/idr")
+            .body(Body::empty())
+            .unwrap()
+    };
+    assert_eq!(send(&app, post()).await.0, StatusCode::CONFLICT);
+
+    state.streaming.store(true, Ordering::SeqCst);
+    assert_eq!(send(&app, post()).await.0, StatusCode::ACCEPTED);
+    assert!(state.force_idr.load(Ordering::SeqCst));
+}
+
+/// The OpenAPI document lists every route with a unique operationId (codegen relies
+/// on both), and the checked-in copy is current.
+#[test]
+fn openapi_document_is_complete_and_checked_in() {
+    let json = openapi_json();
+    let doc: serde_json::Value = serde_json::from_str(&json).unwrap();
+
+    let paths = doc["paths"].as_object().unwrap();
+    for p in [
+        "/api/v1/health",
+        "/api/v1/host",
+        "/api/v1/status",
+        "/api/v1/clients",
+        "/api/v1/clients/{fingerprint}",
+        "/api/v1/pair",
+        "/api/v1/pair/pin",
+        "/api/v1/session",
+        "/api/v1/session/idr",
+    ] {
+        assert!(paths.contains_key(p), "spec is missing {p}");
+    }
+
+    let mut op_ids: Vec<&str> = paths
+        .values()
+        .flat_map(|ops| ops.as_object().unwrap().values())
+        .filter_map(|op| op["operationId"].as_str())
+        .collect();
+    let total = op_ids.len();
+    op_ids.sort_unstable();
+    op_ids.dedup();
+    assert_eq!(total, op_ids.len(), "duplicate operationIds");
+    assert!(doc["components"]["securitySchemes"]["bearerAuth"].is_object());
+    // The health probe overrides the document-global bearer requirement (the server
+    // exempts it in `require_auth`; the spec must agree).
+    assert_eq!(
+        doc["paths"]["/api/v1/health"]["get"]["security"],
+        serde_json::json!([{}])
+    );
+
+    let checked_in = include_str!("../../../../api/openapi.json");
+    // Compare STRUCTURALLY with `info.version` normalized on both sides: the served document
+    // stamps the live crate version, but a version bump alone must never invalidate the
+    // snapshot — the API *surface* is what drift-control protects (the 0.5.0 release tripped
+    // on exactly this). Structural comparison also makes line endings a non-issue (git may
+    // check the file out CRLF on Windows).
+    let mut generated = doc;
+    let mut snapshot: serde_json::Value = serde_json::from_str(checked_in).unwrap();
+    generated["info"]["version"] = serde_json::json!("<any>");
+    snapshot["info"]["version"] = serde_json::json!("<any>");
+    assert_eq!(
+        generated, snapshot,
+        "api/openapi.json is stale — regenerate with: \
+         cargo run -p punktfunk-host -- openapi > api/openapi.json"
+    );
+}
+
+fn post_json(path: &str, body: serde_json::Value) -> axum::http::Request<Body> {
+    axum::http::Request::post(path)
+        .header("content-type", "application/json")
+        .body(Body::from(body.to_string()))
+        .unwrap()
+}
+
+/// The display-management GET surface (presets + effective + the enforced-axes list). READ-ONLY
+/// on purpose: `prefs()` is a process-global `OnceLock`, so a PUT here would clobber it and race
+/// other tests running in the same process. `keep_alive: forever` (gaming-rig) is now accepted
+/// (not rejected) — that acceptance is covered on-glass (`.116`) + by the pure `policy` tests, and
+/// the `forever` value is read off the surfaced preset below without writing.
+#[tokio::test]
+async fn display_settings_surface() {
+    let app = test_app(test_state(), None);
+
+    let (status, body) = send(&app, get_req("/api/v1/display/settings")).await;
+    assert_eq!(status, StatusCode::OK);
+    let presets = body["presets"].as_array().expect("presets array");
+    assert_eq!(
+        presets.len(),
+        5,
+        "all five named presets are surfaced for the console picker"
+    );
+    assert!(
+        body["effective"]["keep_alive"].is_object(),
+        "the effective policy is echoed"
+    );
+    // gaming-rig surfaces keep_alive: forever (no longer rejected) — read it off the preset list.
+    let gaming = presets
+        .iter()
+        .find(|p| p["id"] == "gaming-rig")
+        .expect("gaming-rig preset surfaced");
+    assert_eq!(
+        gaming["fields"]["keep_alive"]["mode"], "forever",
+        "gaming-rig is keep_alive: forever"
+    );
+    let enforced: Vec<&str> = body["enforced"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .filter_map(|v| v.as_str())
+        .collect();
+    // All five axes are enforced now (Stages 0-5).
+    assert!(enforced.contains(&"keep_alive"));
+    assert!(enforced.contains(&"topology"));
+    assert!(enforced.contains(&"mode_conflict"));
+    assert!(enforced.contains(&"identity"));
+    assert!(enforced.contains(&"layout"));
+    // The experimental DDC/CI + PnP-disable axes are acted on (Windows exclusive-isolate path).
+    assert!(enforced.contains(&"ddc_power_off"));
+    assert!(enforced.contains(&"pnp_disable_monitors"));
+}
+
+/// The display state/release endpoints are wired + auth-gated. On the test host no backend has
+/// created a display (and non-Windows reports none), so `/state` is empty and `/release` is a
+/// no-op — the shapes + the "nothing to release" path, without touching any global owner.
+#[tokio::test]
+async fn display_state_and_release_empty() {
+    let app = test_app(test_state(), None);
+
+    let (status, body) = send(&app, get_req("/api/v1/display/state")).await;
+    assert_eq!(status, StatusCode::OK);
+    assert_eq!(
+        body["displays"].as_array().map(|a| a.len()),
+        Some(0),
+        "no managed displays on an idle test host"
+    );
+
+    let (status, body) = send(
+        &app,
+        post_json("/api/v1/display/release", serde_json::json!({})),
+    )
+    .await;
+    assert_eq!(status, StatusCode::OK);
+    assert_eq!(body["released"], 0);
+}
+
+#[tokio::test]
+async fn native_pairing_arm_show_and_unpair() {
+    let np = Arc::new(
+        crate::native_pairing::NativePairing::load_with(
+            Some(std::env::temp_dir().join(format!("pf-mgmt-np-{}.json", std::process::id()))),
+            None,
+            false,
+        )
+        .unwrap(),
+    );
+    let app = test_app_native(test_state(), np.clone());
+
+    // Disarmed: enabled, not armed, no PIN.
+    let (s, b) = send(&app, get_req("/api/v1/native/pair")).await;
+    assert_eq!(s, StatusCode::OK);
+    assert_eq!(b["enabled"], true);
+    assert_eq!(b["armed"], false);
+    assert!(b["pin"].is_null());
+
+    // Arm → a PIN appears and is readable via status.
+    let (s, b) = send(
+        &app,
+        post_json(
+            "/api/v1/native/pair/arm",
+            serde_json::json!({"ttl_secs": 60}),
+        ),
+    )
+    .await;
+    assert_eq!(s, StatusCode::OK);
+    assert_eq!(b["armed"], true);
+    let pin = b["pin"].as_str().unwrap().to_string();
+    assert_eq!(pin.len(), 4);
+    let (_, b) = send(&app, get_req("/api/v1/native/pair")).await;
+    assert_eq!(b["pin"], pin);
+    assert!(b["expires_in_secs"].as_u64().unwrap() <= 60);
+
+    // The QUIC side would read the same live PIN.
+    assert_eq!(np.current_pin().as_deref(), Some(pin.as_str()));
+
+    // Pair a client out-of-band, then it shows in the list + can be unpaired.
+    np.add("Test Device", "abc123").unwrap();
+    let (s, b) = send(&app, get_req("/api/v1/native/clients")).await;
+    assert_eq!(s, StatusCode::OK);
+    assert_eq!(b[0]["name"], "Test Device");
+    assert_eq!(b[0]["fingerprint"], "abc123");
+    let del = axum::http::Request::delete("/api/v1/native/clients/ABC123")
+        .body(Body::empty())
+        .unwrap();
+    assert_eq!(send(&app, del).await.0, StatusCode::NO_CONTENT);
+    let missing = axum::http::Request::delete("/api/v1/native/clients/abc123")
+        .body(Body::empty())
+        .unwrap();
+    assert_eq!(send(&app, missing).await.0, StatusCode::NOT_FOUND);
+
+    // Disarm clears the window.
+    let del = axum::http::Request::delete("/api/v1/native/pair")
+        .body(Body::empty())
+        .unwrap();
+    assert_eq!(send(&app, del).await.0, StatusCode::NO_CONTENT);
+    let (_, b) = send(&app, get_req("/api/v1/native/pair")).await;
+    assert_eq!(b["armed"], false);
+}
+
+#[tokio::test]
+async fn pending_devices_approve_and_deny() {
+    let np = Arc::new(
+        crate::native_pairing::NativePairing::load_with(
+            Some(std::env::temp_dir().join(format!("pf-mgmt-pending-{}.json", std::process::id()))),
+            None,
+            false,
+        )
+        .unwrap(),
+    );
+    let app = test_app_native(test_state(), np.clone());
+
+    // Empty queue.
+    let (s, b) = send(&app, get_req("/api/v1/native/pending")).await;
+    assert_eq!(s, StatusCode::OK);
+    assert_eq!(b.as_array().unwrap().len(), 0);
+
+    // Two devices knock (what the QUIC gate records); they appear in the list.
+    np.note_pending("Enrico's MacBook", "aa11", None);
+    np.note_pending("device bb22cc33", "bb22", None);
+    let (_, b) = send(&app, get_req("/api/v1/native/pending")).await;
+    assert_eq!(b.as_array().unwrap().len(), 2);
+    assert_eq!(b[0]["name"], "Enrico's MacBook");
+    let approve_id = b[0]["id"].as_u64().unwrap();
+    let deny_id = b[1]["id"].as_u64().unwrap();
+
+    // Approve the first with an operator label → paired under that name, gone from pending.
+    let (s, b) = send(
+        &app,
+        post_json(
+            &format!("/api/v1/native/pending/{approve_id}/approve"),
+            serde_json::json!({"name": "Office MacBook"}),
+        ),
+    )
+    .await;
+    assert_eq!(s, StatusCode::OK);
+    assert_eq!(b["name"], "Office MacBook");
+    assert_eq!(b["fingerprint"], "aa11");
+    assert!(np.is_paired("AA11"), "approval pins the fingerprint");
+
+    // Deny the second → dropped, not paired; a re-deny is 404.
+    let deny = post_json(
+        &format!("/api/v1/native/pending/{deny_id}/deny"),
+        serde_json::json!({}),
+    );
+    assert_eq!(send(&app, deny).await.0, StatusCode::NO_CONTENT);
+    assert!(!np.is_paired("bb22"));
+    let (s, _) = send(
+        &app,
+        post_json(
+            &format!("/api/v1/native/pending/{deny_id}/deny"),
+            serde_json::json!({}),
+        ),
+    )
+    .await;
+    assert_eq!(s, StatusCode::NOT_FOUND);
+
+    // Queue is empty again; approving a stale id is 404 (keep `{}` = device's own name).
+    let (_, b) = send(&app, get_req("/api/v1/native/pending")).await;
+    assert_eq!(b.as_array().unwrap().len(), 0);
+    let (s, _) = send(
+        &app,
+        post_json("/api/v1/native/pending/123/approve", serde_json::json!({})),
+    )
+    .await;
+    assert_eq!(s, StatusCode::NOT_FOUND);
+}
+
+#[tokio::test]
+async fn native_endpoints_report_disabled_without_native_host() {
+    let app = test_app(test_state(), None);
+    let (s, b) = send(&app, get_req("/api/v1/native/pair")).await;
+    assert_eq!(s, StatusCode::OK);
+    assert_eq!(b["enabled"], false);
+    // Arming a host that isn't running the native server is a 503.
+    let (s, _) = send(
+        &app,
+        post_json("/api/v1/native/pair/arm", serde_json::json!({})),
+    )
+    .await;
+    assert_eq!(s, StatusCode::SERVICE_UNAVAILABLE);
+    // Pending list reads as an empty array (like /native/clients), not a 503.
+    let (s, b) = send(&app, get_req("/api/v1/native/pending")).await;
+    assert_eq!(s, StatusCode::OK);
+    assert_eq!(b.as_array().unwrap().len(), 0);
+    // Approve/deny without a native host are 503.
+    let (s, _) = send(
+        &app,
+        post_json("/api/v1/native/pending/0/approve", serde_json::json!({})),
+    )
+    .await;
+    assert_eq!(s, StatusCode::SERVICE_UNAVAILABLE);
+    let (s, _) = send(
+        &app,
+        post_json("/api/v1/native/pending/0/deny", serde_json::json!({})),
+    )
+    .await;
+    assert_eq!(s, StatusCode::SERVICE_UNAVAILABLE);
+}
+
+fn put_json(path: &str, body: serde_json::Value) -> axum::http::Request<Body> {
+    axum::http::Request::put(path)
+        .header(axum::http::header::CONTENT_TYPE, "application/json")
+        .body(Body::from(body.to_string()))
+        .unwrap()
+}
+
+/// The GPU endpoints: the inventory GET always answers (an empty list on a GPU-less box —
+/// the schema is platform-independent), and the preference PUT validates mode + gpu_id
+/// BEFORE touching the persisted store, so a bad request can never write.
+#[tokio::test]
+async fn gpu_endpoints_list_and_validate() {
+    let app = test_app(test_state(), None);
+
+    let (s, b) = send(&app, get_req("/api/v1/gpus")).await;
+    assert_eq!(s, StatusCode::OK);
+    assert!(b["gpus"].is_array());
+    assert!(b["mode"].is_string());
+
+    // Unknown mode → 400.
+    let (s, _) = send(
+        &app,
+        put_json(
+            "/api/v1/gpus/preference",
+            serde_json::json!({"mode": "fastest"}),
+        ),
+    )
+    .await;
+    assert_eq!(s, StatusCode::BAD_REQUEST);
+
+    // `manual` without a gpu_id → 400.
+    let (s, _) = send(
+        &app,
+        put_json(
+            "/api/v1/gpus/preference",
+            serde_json::json!({"mode": "manual"}),
+        ),
+    )
+    .await;
+    assert_eq!(s, StatusCode::BAD_REQUEST);
+
+    // `manual` with an id that is not a present GPU → 400 (the console only offers listed ids).
+    let (s, _) = send(
+        &app,
+        put_json(
+            "/api/v1/gpus/preference",
+            serde_json::json!({"mode": "manual", "gpu_id": "ffff-ffff-9"}),
+        ),
+    )
+    .await;
+    assert_eq!(s, StatusCode::BAD_REQUEST);
+}
+
+#[tokio::test]
+async fn logs_endpoint_pages_by_cursor() {
+    let app = test_app(test_state(), None);
+
+    // The ring is a process-wide singleton — start from wherever its cursor currently is.
+    let (s, json) = send(&app, get_req("/api/v1/logs")).await;
+    assert_eq!(s, StatusCode::OK);
+    let start = json["next"].as_u64().unwrap();
+
+    let ring = crate::log_capture::ring();
+    ring.push(&tracing::Level::WARN, "mgmt::tests", "first".into());
+    ring.push(&tracing::Level::INFO, "mgmt::tests", "second".into());
+
+    let (s, json) = send(&app, get_req(&format!("/api/v1/logs?after={start}"))).await;
+    assert_eq!(s, StatusCode::OK);
+    let entries = json["entries"].as_array().unwrap();
+    assert_eq!(entries.len(), 2);
+    assert_eq!(entries[0]["msg"], "first");
+    assert_eq!(entries[0]["level"], "WARN");
+    assert_eq!(json["next"].as_u64().unwrap(), start + 2);
+    assert_eq!(json["dropped"], false);
+
+    // Nothing newer → empty page, cursor unchanged.
+    let after = start + 2;
+    let (s, json) = send(&app, get_req(&format!("/api/v1/logs?after={after}"))).await;
+    assert_eq!(s, StatusCode::OK);
+    assert!(json["entries"].as_array().unwrap().is_empty());
+    assert_eq!(json["next"].as_u64().unwrap(), after);
+}