feat(core,host,clients): typed pairing rejections — every client says WHY, not "not accepted"

A host's pairing-gate rejections (not armed / bound to another device /
rate-limited / identity required / denied / approval timeout / superseded /
wire-version mismatch) used to drop the connection with a bare code-0 close,
and every client collapsed that — plus plain unreachability — into one
"wrong PIN / not accepted" message. A dead network path, a disarmed host,
and an operator denial were indistinguishable, which is exactly the
misdiagnosis behind the recent Android pairing support thread.

- core: new ungated `reject` module — shared close-code block 0x60–0x67
  (+ 0x42 busy promoted from the host), `RejectReason`, and
  `PunktfunkError::Rejected`; `pair()`/`connect()` decode the host's
  ApplicationClosed code into `Rejected` instead of a generic Io error.
  C ABI v7: status block −20…−28 and `punktfunk_connect_ex8` (`status_out`
  reports the failure cause; NULL-return alone can't). Wire unchanged —
  old peers see exactly the old bare close.
- host: every gate rejection `conn.close()`s with its typed code (and the
  human reason as close bytes) before erroring out of the session task.
- pf-client-core: shared `pair_error_message`/`connect_reject_message`
  wording consumed by the Windows + Linux + console-UI + CLI surfaces; a
  connect failure now renders the host's stated reason.
- android: `nativeTakeLastError()` JNI token + `ConnectErrors.kt` — a
  network timeout is no longer reported as "wrong PIN, or the host isn't
  armed", and a typed rejection skips the wake-and-wait fallback (the host
  is demonstrably awake).
- apple: `HostRejection` + `.rejected`; the pair sheet and session alerts
  show the stated reason; connect moves to `ex8`.

Completes the cross-client half of the hunks that rode along in 12148243
(client.rs / trust.rs / punktfunk1.rs) — main did not build without this.

Validated: workspace clippy -D warnings + full test suite green on .21
(EXIT=0, 309 host / 148 core suites); macOS core 147+c_abi green; swift
build green; Android Kotlin + native crate green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

crates/punktfunk-core/src/abi.rs

@@ -1337,13 +1337,132 @@ pub unsafe extern "C" fn punktfunk_connect_ex7(
     client_key_pem: *const std::os::raw::c_char,
     timeout_ms: u32,
 ) -> *mut PunktfunkConnection {
+    unsafe {
+        connect_ex_impl(
+            host,
+            port,
+            width,
+            height,
+            refresh_hz,
+            compositor,
+            gamepad,
+            bitrate_kbps,
+            video_caps,
+            audio_channels,
+            video_codecs,
+            preferred_codec,
+            launch_id,
+            pin_sha256,
+            observed_sha256_out,
+            client_cert_pem,
+            client_key_pem,
+            timeout_ms,
+            std::ptr::null_mut(),
+        )
+    }
+}
+
+/// Like [`punktfunk_connect_ex7`], but additionally reports WHY a failed connect failed:
+/// `status_out` (nullable — null is exactly `ex7`) receives a [`PunktfunkStatus`] as `i32` —
+/// `Ok` on success, the mapped error otherwise, including the typed host-rejection block
+/// (`PUNKTFUNK_STATUS_REJECTED_NOT_ARMED` … `PUNKTFUNK_STATUS_REJECTED_BUSY`) decoded from the
+/// host's application close. That lets an embedder tell "denied in the console" / "nobody
+/// approved in time" / "host busy" / "versions don't match" apart from plain unreachability
+/// (`Io`/`Timeout`) — a NULL return alone can't say which.
+///
+/// # Safety
+/// Same as [`punktfunk_connect`]; `status_out`, when non-null, must point to a writable `i32`.
+#[cfg(feature = "quic")]
+#[no_mangle]
+#[allow(clippy::too_many_arguments)]
+pub unsafe extern "C" fn punktfunk_connect_ex8(
+    host: *const std::os::raw::c_char,
+    port: u16,
+    width: u32,
+    height: u32,
+    refresh_hz: u32,
+    compositor: u32,
+    gamepad: u32,
+    bitrate_kbps: u32,
+    video_caps: u8,
+    audio_channels: u8,
+    video_codecs: u8,
+    preferred_codec: u8,
+    launch_id: *const std::os::raw::c_char,
+    pin_sha256: *const u8,
+    observed_sha256_out: *mut u8,
+    client_cert_pem: *const std::os::raw::c_char,
+    client_key_pem: *const std::os::raw::c_char,
+    timeout_ms: u32,
+    status_out: *mut i32,
+) -> *mut PunktfunkConnection {
+    unsafe {
+        connect_ex_impl(
+            host,
+            port,
+            width,
+            height,
+            refresh_hz,
+            compositor,
+            gamepad,
+            bitrate_kbps,
+            video_caps,
+            audio_channels,
+            video_codecs,
+            preferred_codec,
+            launch_id,
+            pin_sha256,
+            observed_sha256_out,
+            client_cert_pem,
+            client_key_pem,
+            timeout_ms,
+            status_out,
+        )
+    }
+}
+
+/// Shared body of [`punktfunk_connect_ex7`] / [`punktfunk_connect_ex8`]: `status_out`
+/// (nullable) is written on EVERY path — `Ok`, the mapped [`PunktfunkError`],
+/// `InvalidArg` for bad arguments, `Panic` if the connect panicked.
+#[cfg(feature = "quic")]
+#[allow(clippy::too_many_arguments)]
+unsafe fn connect_ex_impl(
+    host: *const std::os::raw::c_char,
+    port: u16,
+    width: u32,
+    height: u32,
+    refresh_hz: u32,
+    compositor: u32,
+    gamepad: u32,
+    bitrate_kbps: u32,
+    video_caps: u8,
+    audio_channels: u8,
+    video_codecs: u8,
+    preferred_codec: u8,
+    launch_id: *const std::os::raw::c_char,
+    pin_sha256: *const u8,
+    observed_sha256_out: *mut u8,
+    client_cert_pem: *const std::os::raw::c_char,
+    client_key_pem: *const std::os::raw::c_char,
+    timeout_ms: u32,
+    status_out: *mut i32,
+) -> *mut PunktfunkConnection {
+    let set_status = |s: crate::error::PunktfunkStatus| {
+        if !status_out.is_null() {
+            unsafe { *status_out = s as i32 };
+        }
+    };
     let r = std::panic::catch_unwind(AssertUnwindSafe(|| {
         if host.is_null() {
+            set_status(crate::error::PunktfunkStatus::InvalidArg);
             return std::ptr::null_mut();
         }
         let host = match unsafe { std::ffi::CStr::from_ptr(host) }.to_str() {
             Ok(s) => s,
-            Err(_) => return std::ptr::null_mut(),
+            Err(_) => {
+                set_status(crate::error::PunktfunkStatus::InvalidArg);
+                return std::ptr::null_mut();
+            }
         };
         // A bad-UTF-8 launch id is non-fatal — treat it as "no game" rather than failing connect.
         let launch = match unsafe { opt_cstr(launch_id) } {
@@ -1375,7 +1494,11 @@ pub unsafe extern "C" fn punktfunk_connect_ex7(
         }) {
             (Ok(Some(c)), Ok(Some(k))) => Some((c.to_string(), k.to_string())),
             (Ok(None), Ok(None)) => None,
-            _ => return std::ptr::null_mut(), // half an identity / bad UTF-8: fail closed
+            _ => {
+                // Half an identity / bad UTF-8: fail closed.
+                set_status(crate::error::PunktfunkStatus::InvalidArg);
+                return std::ptr::null_mut();
+            }
         };
         match crate::client::NativeClient::connect(
             host,
@@ -1404,6 +1527,7 @@ pub unsafe extern "C" fn punktfunk_connect_ex7(
                             .copy_from_slice(&c.host_fingerprint);
                     }
                 }
+                set_status(crate::error::PunktfunkStatus::Ok);
                 Box::into_raw(Box::new(PunktfunkConnection {
                     inner: c,
                     last: std::sync::Mutex::new(None),
@@ -1411,10 +1535,16 @@ pub unsafe extern "C" fn punktfunk_connect_ex7(
                     audio_pcm: std::sync::Mutex::new(AudioPcmState::default()),
                 }))
             }
-            Err(_) => std::ptr::null_mut(),
+            Err(e) => {
+                set_status(e.status());
+                std::ptr::null_mut()
+            }
         }
     }));
-    r.unwrap_or(std::ptr::null_mut())
+    r.unwrap_or_else(|_| {
+        set_status(crate::error::PunktfunkStatus::Panic);
+        std::ptr::null_mut()
+    })
 }
 
 /// Generate a persistent client identity: a self-signed certificate + private key, both

crates/punktfunk-core/src/error.rs

@@ -23,6 +23,12 @@ pub enum PunktfunkError {
     Timeout,
     #[error("session closed")]
     Closed,
+    /// The host deliberately turned this connection away and said why (a typed QUIC application
+    /// close, [`crate::reject::RejectReason`]) — distinct from transport trouble ([`Self::Io`] /
+    /// [`Self::Timeout`]) and from a failed PIN proof ([`Self::Crypto`]) so UIs can render the
+    /// real cause instead of a generic "not accepted".
+    #[error("rejected by host: {0}")]
+    Rejected(crate::reject::RejectReason),
 }
 
 pub type Result<T> = core::result::Result<T, PunktfunkError>;
@@ -43,6 +49,18 @@ pub enum PunktfunkStatus {
     NullPointer = -8,
     Timeout = -9,
     Closed = -10,
+    // -11..-19 reserved for future generic errors. The -20 block mirrors
+    // `crate::reject::RejectReason` one-to-one so FFI callers (Swift, JNI) can
+    // render the host's actual rejection reason.
+    RejectedNotArmed = -20,
+    RejectedBoundOther = -21,
+    RejectedRateLimited = -22,
+    RejectedIdentityRequired = -23,
+    RejectedDenied = -24,
+    RejectedApprovalTimeout = -25,
+    RejectedSuperseded = -26,
+    RejectedWireVersion = -27,
+    RejectedBusy = -28,
     Panic = -99,
 }
 
@@ -59,6 +77,20 @@ impl PunktfunkError {
             PunktfunkError::Io(_) => PunktfunkStatus::Io,
             PunktfunkError::Timeout => PunktfunkStatus::Timeout,
             PunktfunkError::Closed => PunktfunkStatus::Closed,
+            PunktfunkError::Rejected(r) => {
+                use crate::reject::RejectReason as R;
+                match r {
+                    R::PairingNotArmed => PunktfunkStatus::RejectedNotArmed,
+                    R::PairingBoundToOtherDevice => PunktfunkStatus::RejectedBoundOther,
+                    R::PairingRateLimited => PunktfunkStatus::RejectedRateLimited,
+                    R::IdentityRequired => PunktfunkStatus::RejectedIdentityRequired,
+                    R::Denied => PunktfunkStatus::RejectedDenied,
+                    R::ApprovalTimeout => PunktfunkStatus::RejectedApprovalTimeout,
+                    R::Superseded => PunktfunkStatus::RejectedSuperseded,
+                    R::WireVersionMismatch => PunktfunkStatus::RejectedWireVersion,
+                    R::Busy => PunktfunkStatus::RejectedBusy,
+                }
+            }
         }
     }
 }

crates/punktfunk-core/src/lib.rs

@@ -39,6 +39,7 @@ pub mod packet;
 #[cfg(feature = "quic")]
 pub mod quic;
 pub mod reanchor;
+pub mod reject;
 pub mod session;
 pub mod stats;
 pub mod transport;
@@ -65,7 +66,12 @@ pub use stats::Stats;
 /// v6: added the `punktfunk_reanchor_gate_*` surface (post-loss freeze-until-reanchor gate for the
 /// Swift client; Rust embedders use [`reanchor::ReanchorGate`] directly). Additive, client-local —
 /// no wire change, so [`WIRE_VERSION`] is unchanged.
-pub const ABI_VERSION: u32 = 6;
+/// v7: added `punktfunk_connect_ex8` (`status_out` — typed connect-failure reporting, including
+/// the host-rejection block `PUNKTFUNK_STATUS_REJECTED_*` decoded from the host's QUIC
+/// application close) and the `PunktfunkStatus` −20 block itself. Additive — the close codes are
+/// new application-close vocabulary an old peer simply never sends/reads, so [`WIRE_VERSION`] is
+/// unchanged.
+pub const ABI_VERSION: u32 = 7;
 
 /// The punktfunk/1 **wire** version — what `Hello`/`Welcome` carry and hosts equality-check.
 /// Deliberately its own constant: [`ABI_VERSION`] tracks the embeddable **C surface**

crates/punktfunk-core/src/quic/msgs.rs

@@ -135,6 +135,11 @@ pub const QUIT_CLOSE_CODE: u32 = 0x51;
 /// returns to its launcher on session end), so it is purely refinement. Shared so host + clients agree.
 pub const APP_EXITED_CLOSE_CODE: u32 = 0x52;
 
+// Typed rejection close codes + [`RejectReason`] live in `crate::reject` (ungated — the
+// error enum references them even in `quic`-less builds) and are re-exported here so the
+// wire vocabulary stays browsable next to QUIT/APP_EXITED.
+pub use crate::reject::*;
+
 /// [`Welcome::host_caps`] bit: the host applies [`InputKind::GamepadState`]
 /// (crate::input::InputKind::GamepadState) snapshot events — full per-pad state with a reorder
 /// sequence number. A capable client then sends gamepad state as snapshots (idempotent on the

crates/punktfunk-core/src/reject.rs

@@ -0,0 +1,171 @@
+//! Why a host turns a connection away: typed QUIC application close codes + the
+//! [`RejectReason`] vocabulary shared by host and every client. Lives OUTSIDE the `quic`
+//! feature gate because [`PunktfunkError::Rejected`](crate::error::PunktfunkError::Rejected)
+//! carries it in every build; `crate::quic` re-exports it.
+
+/// QUIC application error code the host closes with on a `mode_conflict = reject` admission
+/// refusal, carrying the human-readable busy reason (live mode + client label). A distinct code
+/// lets a client tell "host busy" apart from a transport failure. Shared so clients can render it.
+pub const REJECT_BUSY_CLOSE_CODE: u32 = 0x42;
+
+/// QUIC application close codes the host sends on **pairing-gate rejections**, so a client can
+/// tell the user WHY it was turned away instead of collapsing every close into a generic
+/// "not accepted" (the failure mode behind more than one support thread: a PIN attempt against a
+/// disarmed host, an operator denial, and a dead network path all looked identical). Grouped in
+/// their own 0x60 block, disjoint from [`REJECT_BUSY_CLOSE_CODE`] (0x42) and the deliberate-end
+/// codes (0x51/0x52). Purely additive: an older client treats them as a bare close (exactly the
+/// pre-code behavior), an older host never sends them. Decode with [`RejectReason::from_close_code`].
+pub const PAIR_NOT_ARMED_CLOSE_CODE: u32 = 0x60;
+/// Pairing window armed, but bound to a DIFFERENT device fingerprint (the attempt does not
+/// consume the window). See [`PAIR_NOT_ARMED_CLOSE_CODE`] for the block's contract.
+pub const PAIR_BOUND_OTHER_CLOSE_CODE: u32 = 0x61;
+/// PIN attempt inside the host's global pairing cooldown — retry shortly.
+pub const PAIR_RATE_LIMITED_CLOSE_CODE: u32 = 0x62;
+/// Unpaired client presented no certificate: nothing to approve, and the SPAKE2 ceremony needs an
+/// identity to bind — the PIN flow with a client identity is the way in.
+pub const PAIR_NO_IDENTITY_CLOSE_CODE: u32 = 0x63;
+/// The operator explicitly denied this pairing request in the host console.
+pub const PAIR_DENIED_CLOSE_CODE: u32 = 0x64;
+/// Nobody decided on the parked pairing request before the host's approval wait elapsed.
+pub const PAIR_APPROVAL_TIMEOUT_CLOSE_CODE: u32 = 0x65;
+/// This parked knock was superseded by a newer connection from the same device — only the
+/// newest is admitted on approval.
+pub const PAIR_SUPERSEDED_CLOSE_CODE: u32 = 0x66;
+/// The client's wire (protocol) version does not match the host's — one side needs updating.
+pub const WIRE_VERSION_CLOSE_CODE: u32 = 0x67;
+
+/// Why a host turned a connection away, decoded from the QUIC application close code — the
+/// client-side view of [`PAIR_NOT_ARMED_CLOSE_CODE`]..[`WIRE_VERSION_CLOSE_CODE`] plus
+/// [`REJECT_BUSY_CLOSE_CODE`]. Surfaces as
+/// [`PunktfunkError::Rejected`](crate::error::PunktfunkError::Rejected) so every client can show
+/// the real reason ("pairing not armed", "denied in the console") instead of a generic failure.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RejectReason {
+    /// No pairing window is armed on the host (arm it in the console).
+    PairingNotArmed,
+    /// The armed window is bound to a different device fingerprint.
+    PairingBoundToOtherDevice,
+    /// Inside the host's pairing cooldown — retry shortly.
+    PairingRateLimited,
+    /// The client presented no certificate identity to approve/bind.
+    IdentityRequired,
+    /// The operator denied the request in the console.
+    Denied,
+    /// The parked request expired with no operator decision.
+    ApprovalTimeout,
+    /// A newer knock from the same device replaced this one.
+    Superseded,
+    /// Client/host wire versions differ.
+    WireVersionMismatch,
+    /// The host refused admission because a conflicting session is live.
+    Busy,
+}
+
+impl RejectReason {
+    /// Decode a QUIC application close code into a reason; `None` for codes outside the
+    /// shared vocabulary (a bare/legacy close stays a plain transport error).
+    pub fn from_close_code(code: u32) -> Option<Self> {
+        Some(match code {
+            PAIR_NOT_ARMED_CLOSE_CODE => Self::PairingNotArmed,
+            PAIR_BOUND_OTHER_CLOSE_CODE => Self::PairingBoundToOtherDevice,
+            PAIR_RATE_LIMITED_CLOSE_CODE => Self::PairingRateLimited,
+            PAIR_NO_IDENTITY_CLOSE_CODE => Self::IdentityRequired,
+            PAIR_DENIED_CLOSE_CODE => Self::Denied,
+            PAIR_APPROVAL_TIMEOUT_CLOSE_CODE => Self::ApprovalTimeout,
+            PAIR_SUPERSEDED_CLOSE_CODE => Self::Superseded,
+            WIRE_VERSION_CLOSE_CODE => Self::WireVersionMismatch,
+            REJECT_BUSY_CLOSE_CODE => Self::Busy,
+            _ => return None,
+        })
+    }
+
+    /// The close code this reason travels as (inverse of [`Self::from_close_code`]).
+    pub fn close_code(self) -> u32 {
+        match self {
+            Self::PairingNotArmed => PAIR_NOT_ARMED_CLOSE_CODE,
+            Self::PairingBoundToOtherDevice => PAIR_BOUND_OTHER_CLOSE_CODE,
+            Self::PairingRateLimited => PAIR_RATE_LIMITED_CLOSE_CODE,
+            Self::IdentityRequired => PAIR_NO_IDENTITY_CLOSE_CODE,
+            Self::Denied => PAIR_DENIED_CLOSE_CODE,
+            Self::ApprovalTimeout => PAIR_APPROVAL_TIMEOUT_CLOSE_CODE,
+            Self::Superseded => PAIR_SUPERSEDED_CLOSE_CODE,
+            Self::WireVersionMismatch => WIRE_VERSION_CLOSE_CODE,
+            Self::Busy => REJECT_BUSY_CLOSE_CODE,
+        }
+    }
+
+    /// Stable machine token (kebab-case) for FFI layers that pass the reason as a string
+    /// (e.g. the Android JNI bridge). Do not reword existing tokens — clients match on them.
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::PairingNotArmed => "not-armed",
+            Self::PairingBoundToOtherDevice => "bound-other",
+            Self::PairingRateLimited => "rate-limited",
+            Self::IdentityRequired => "identity-required",
+            Self::Denied => "denied",
+            Self::ApprovalTimeout => "approval-timeout",
+            Self::Superseded => "superseded",
+            Self::WireVersionMismatch => "wire-version",
+            Self::Busy => "busy",
+        }
+    }
+}
+
+impl std::fmt::Display for RejectReason {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(match self {
+            Self::PairingNotArmed => "pairing is not armed on the host",
+            Self::PairingBoundToOtherDevice => {
+                "the host's pairing window is armed for a different device"
+            }
+            Self::PairingRateLimited => "pairing attempts are rate-limited — retry shortly",
+            Self::IdentityRequired => "the host requires a client identity",
+            Self::Denied => "the request was denied on the host",
+            Self::ApprovalTimeout => "nobody approved the request on the host in time",
+            Self::Superseded => "a newer request from this device replaced this one",
+            Self::WireVersionMismatch => "client and host versions do not match",
+            Self::Busy => "the host is busy with another session",
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const ALL: [RejectReason; 9] = [
+        RejectReason::PairingNotArmed,
+        RejectReason::PairingBoundToOtherDevice,
+        RejectReason::PairingRateLimited,
+        RejectReason::IdentityRequired,
+        RejectReason::Denied,
+        RejectReason::ApprovalTimeout,
+        RejectReason::Superseded,
+        RejectReason::WireVersionMismatch,
+        RejectReason::Busy,
+    ];
+
+    #[test]
+    fn close_codes_round_trip() {
+        for r in ALL {
+            assert_eq!(RejectReason::from_close_code(r.close_code()), Some(r));
+        }
+    }
+
+    #[test]
+    fn codes_are_unique() {
+        let mut codes: Vec<u32> = ALL.iter().map(|r| r.close_code()).collect();
+        codes.sort_unstable();
+        codes.dedup();
+        assert_eq!(codes.len(), ALL.len());
+    }
+
+    #[test]
+    fn foreign_codes_stay_untyped() {
+        // Bare closes, the client's own pair-done codes, and the deliberate-end codes must
+        // never read as a host rejection.
+        for code in [0u32, 1, 0x41, 0x51, 0x52, 0x5f, 0x68, u32::MAX] {
+            assert_eq!(RejectReason::from_close_code(code), None);
+        }
+    }
+}