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>

clients/android/app/src/main/kotlin/io/unom/punktfunk/ConnectDialogs.kt

@@ -303,7 +303,8 @@ internal fun PairPinDialog(
                             if (fp.isNotEmpty()) {
                                 onPaired(fp) // verified host fp — caller saves + connects
                             } else {
-                                err = "Pairing failed — wrong PIN, or the host isn't armed."
+                                // Cause-specific: wrong PIN vs not-armed vs unreachable.
+                                err = ConnectErrors.pairMessage(NativeBridge.nativeTakeLastError())
                             }
                         }
                     }

clients/android/app/src/main/kotlin/io/unom/punktfunk/ConnectErrors.kt

@@ -0,0 +1,69 @@
+package io.unom.punktfunk
+
+import io.unom.punktfunk.kit.NativeBridge
+
+/**
+ * Cause-specific user-facing messages for failed pair/connect attempts, keyed on the stable
+ * machine token from [NativeBridge.nativeTakeLastError]. One vocabulary for both the PIN
+ * ceremony and the request-access (delegated approval) path, so a dead network path is never
+ * reported as "wrong PIN" and an operator denial is never reported as a timeout — the exact
+ * collapse behind more than one support thread.
+ */
+object ConnectErrors {
+    /** Message for a failed SPAKE2 PIN ceremony ([NativeBridge.nativePair] returned `""`). */
+    fun pairMessage(token: String): String = when (token) {
+        "crypto" -> "Wrong PIN — check the PIN on the host's Pairing page and try again."
+        else -> shared(token) ?: transport(token)
+    }
+
+    /**
+     * Message for a failed connect / request-access ([NativeBridge.nativeConnect] returned `0`).
+     * [requestAccess] tunes the fallback wording for the delegated-approval path.
+     */
+    fun connectMessage(token: String, requestAccess: Boolean): String =
+        shared(token) ?: when (token) {
+            "crypto" ->
+                "The host's identity doesn't match the saved fingerprint — re-pair with this host."
+            "timeout", "io", "" ->
+                if (requestAccess) {
+                    "The request never reached the host, or nobody approved it in time — " +
+                        "check the network path (no VPN, no guest-Wi-Fi isolation) and the " +
+                        "host's console."
+                } else {
+                    transport(token)
+                }
+            else -> "Connection failed — check host/port and logcat."
+        }
+
+    /** The host's typed rejection reasons — identical wording across every punktfunk client. */
+    private fun shared(token: String): String? = when (token) {
+        "not-armed" ->
+            "Pairing isn't armed on the host — arm it on the host's Pairing page, then try again."
+        "bound-other" ->
+            "The host's pairing window is armed for a different device — arm it for this one."
+        "rate-limited" -> "Too many pairing attempts — wait a couple of seconds and try again."
+        "identity-required" ->
+            "The host requires pairing — pair this device (PIN or request access) first."
+        "denied" -> "The host declined this device's request."
+        "approval-timeout" ->
+            "Nobody approved the request on the host in time — approve this device in the " +
+                "host's console or web UI, then request access again."
+        "superseded" ->
+            "A newer request from this device replaced this one — approve the latest request " +
+                "on the host."
+        "wire-version" -> "Client and host versions don't match — update both to the same release."
+        "busy" -> "The host is busy with another session."
+        else -> null
+    }
+
+    /** Transport-level causes (nothing typed arrived from the host). */
+    private fun transport(token: String): String = when (token) {
+        "timeout" ->
+            "The host didn't answer — check that this device and the host are on the same " +
+                "network (no VPN on this device, no guest-Wi-Fi / AP isolation)."
+        "io" ->
+            "Couldn't reach the host — check that this device and the host are on the same " +
+                "network (no VPN on this device, no guest-Wi-Fi / AP isolation)."
+        else -> "Pairing failed — the host didn't answer or closed the connection (see logcat)."
+    }
+}

clients/android/app/src/main/kotlin/io/unom/punktfunk/ConnectScreen.kt

@@ -305,13 +305,17 @@ fun ConnectScreen(
                 onConnected(handle)
             } else {
                 discovery.start()
-                if (onFailure != null) {
-                    // Hand off to the wake-and-wait flow — clearing `attempt` above and setting
-                    // `waker.waking` here land in one recompose, so the overlay slides
+                val token = NativeBridge.nativeTakeLastError()
+                val unreachable = token == "timeout" || token == "io" || token.isEmpty()
+                if (onFailure != null && unreachable) {
+                    // Unreachable — hand off to the wake-and-wait flow — clearing `attempt` above
+                    // and setting `waker.waking` here land in one recompose, so the overlay slides
                     // Connecting → Waking without a blank frame.
                     onFailure()
                 } else {
-                    status = "Connection failed — check host/port, PIN, and logcat"
+                    // A typed host rejection (busy / versions differ / pairing required) means the
+                    // host is awake — waking it would be nonsense; show the stated reason instead.
+                    status = ConnectErrors.connectMessage(token, requestAccess = false)
                 }
             }
         }
@@ -416,7 +420,12 @@ fun ConnectScreen(
                 }
                 onConnected(handle)
             } else {
-                status = "Request timed out — approve this device in the host's console, then retry."
+                // Cause-specific: an operator denial, an approval timeout, and a request that
+                // never reached the host are different problems with different fixes.
+                status = ConnectErrors.connectMessage(
+                    NativeBridge.nativeTakeLastError(),
+                    requestAccess = true,
+                )
                 discovery.start()
             }
         }

clients/android/app/src/main/kotlin/io/unom/punktfunk/GamepadDialogs.kt

@@ -351,7 +351,12 @@ fun GamepadPairPinDialog(pt: PendingTrust, identity: ClientIdentity?, onPaired:
                 NativeBridge.nativePair(pt.host, pt.port, id.certPem, id.privateKeyPem, pin, name)
             }
             pairing = false
-            if (fp.isNotEmpty()) onPaired(fp) else err = "Pairing failed — wrong PIN, or the host isn't armed."
+            if (fp.isNotEmpty()) {
+                onPaired(fp)
+            } else {
+                // Cause-specific: wrong PIN vs not-armed vs unreachable.
+                err = ConnectErrors.pairMessage(NativeBridge.nativeTakeLastError())
+            }
         }
     }
 

clients/android/kit/src/main/kotlin/io/unom/punktfunk/kit/NativeBridge.kt

@@ -85,6 +85,16 @@ object NativeBridge {
         name: String,
     ): String
 
+    /**
+     * The machine token of the most recent failed [nativeConnect]/[nativePair], cleared on read
+     * (`""` when none) — call right after a `0` handle / `""` fingerprint. A typed host rejection
+     * yields its wire token ("not-armed", "denied", "approval-timeout", "superseded", "busy",
+     * "rate-limited", "bound-other", "identity-required", "wire-version"); transport-level causes
+     * yield "crypto" (wrong PIN / identity mismatch), "timeout", "io", or "error". Lets the UI say
+     * WHY instead of the old catch-all that blamed the PIN for dead network paths.
+     */
+    external fun nativeTakeLastError(): String
+
     /**
      * Signal a **deliberate** user disconnect on [handle] before [nativeClose]: the session closes
      * with `QUIT_CLOSE_CODE` so the host tears it down immediately instead of holding the keep-alive

clients/android/native/src/session/connect.rs

@@ -11,6 +11,43 @@ use std::time::Duration;
 
 use super::{hex32, jni_guard, parse_hex32, SessionHandle};
 
+/// Machine token of the most recent `nativeConnect`/`nativePair` failure, taken (and cleared)
+/// by `nativeTakeLastError` so Kotlin can render a cause-specific message instead of the old
+/// catch-all "wrong PIN, or the host isn't armed" (which blamed the PIN for dead network paths
+/// — the moko0878-class support threads). The app runs one attempt at a time, so one slot
+/// suffices; a stale token is harmless (it is taken immediately after the failed call).
+static LAST_ERROR: Mutex<String> = Mutex::new(String::new());
+
+/// Stable token for a failed pair/connect cause, matched by Kotlin (`ConnectErrors.kt`):
+/// a typed host rejection yields its `RejectReason::as_str()` token ("not-armed", "denied",
+/// "approval-timeout", …); transport-level causes map to "crypto" / "timeout" / "io" / "error".
+fn note_error(e: &punktfunk_core::error::PunktfunkError) {
+    use punktfunk_core::error::PunktfunkError as E;
+    let token = match e {
+        E::Rejected(r) => r.as_str(),
+        E::Crypto => "crypto",
+        E::Timeout => "timeout",
+        E::Io(_) => "io",
+        _ => "error",
+    };
+    *LAST_ERROR.lock().unwrap() = token.to_string();
+}
+
+/// `NativeBridge.nativeTakeLastError(): String` — the machine token of the most recent failed
+/// `nativeConnect`/`nativePair`, cleared on read (`""` when none). Call right after a `0`
+/// handle / `""` fingerprint.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeTakeLastError<'local>(
+    env: JNIEnv<'local>,
+    _this: JObject<'local>,
+) -> jni::sys::jstring {
+    let token = std::mem::take(&mut *LAST_ERROR.lock().unwrap());
+    match env.new_string(token) {
+        Ok(s) => s.into_raw(),
+        Err(_) => JObject::null().into_raw(),
+    }
+}
+
 /// `NativeBridge.nativeGenerateIdentity(): String` — mint a fresh persistent self-signed identity.
 /// Returns `"<certPem>\n-----PUNKTFUNK-KEY-----\n<keyPem>"`, or `""` on failure (logged). Kotlin
 /// persists it (Keystore-wrapped) and only calls this again when the store is genuinely empty.
@@ -185,6 +222,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'lo
         }
         Err(e) => {
             log::error!("nativeConnect to {host}:{port} failed: {e}");
+            note_error(&e);
             0
         }
     }
@@ -318,7 +356,9 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativePair<'local
             Ok(host_fp) => hex32(&host_fp),
             Err(e) => {
                 // Crypto error == wrong PIN / MITM; anything else == transport/host reject.
+                // The token lets Kotlin say WHICH (`nativeTakeLastError`).
                 log::error!("nativePair to {host}:{port} failed: {e}");
+                note_error(&e);
                 String::new()
             }
         }