docs: add BRANCH-android-rewrite.md and update ARCH/ADMIN/USER_GUIDE

Documents the android-rewrite branch story end-to-end:
- Why the Kotlin+JNI stack was abandoned (stack overflow, libcrypto
  TLS race, __init_tcb TCB leak, ring runtime reuse crash)
- The Tauri 2.x Mobile pivot that reuses the desktop codebase verbatim
- Android-specific pieces: wzp-native standalone cdylib loaded via
  libloading, android_audio.rs JVM routing, Oboe audio config quirks
- Build pipeline via build-tauri-android.sh + wzp-android-builder image
- Known quirks (API 34/36 coexistence, NDK path absolutes, etc.)

Also appends shared-doc sections (identical on both branches):
- ARCHITECTURE.md: "Audio Backend Architecture (Platform Matrix)"
  covering CPAL / VPIO / WASAPI / Oboe backends, selection matrix,
  the wzp-native cdylib rationale, and the vendored audiopus_sys fix.
- ADMINISTRATION.md: "Build Pipelines" with Docker images
  (wzp-android-builder, wzp-windows-builder), per-pipeline usage
  (Android APK, Linux x86_64, Windows .exe), the Hetzner Cloud
  alternative, ntfy/rustypaste integration, and credential locations.
- USER_GUIDE.md: "Direct 1:1 Calling (Desktop + Android)" covering
  history + recent contacts + deregister UI, and "Windows AEC
  Variants" explaining the AEC vs noAEC builds and driver caveats.

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

.gitignore

@@ -4,3 +4,28 @@
 *.swp
 *.swo
 *~
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+dev-debug.log
+# Dependency directories
+node_modules/
+# Environment variables
+.env
+# Editor directories and files
+.idea
+.vscode
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+# OS specific
+
+# Taskmaster (local workflow tool)
+.taskmaster/
+.env.example

Cargo.lock

@@ -4370,6 +4370,7 @@ dependencies = [
  "async-trait",
  "axum 0.7.9",
  "bytes",
+ "chrono",
  "dirs",
  "futures-util",
  "prometheus",
@@ -4378,6 +4379,7 @@ dependencies = [
  "rustls",
  "serde",
  "serde_json",
+ "sha2",
  "tokio",
  "toml",
  "tower-http",
@@ -4397,10 +4399,13 @@ version = "0.1.0"
 dependencies = [
  "async-trait",
  "bytes",
+ "ed25519-dalek",
+ "hkdf",
  "quinn",
  "rcgen",
  "rustls",
  "serde_json",
+ "sha2",
  "tokio",
  "tracing",
  "wzp-proto",

android/app/src/main/java/com/wzp/engine/CallStats.kt

@@ -33,10 +33,24 @@ data class CallStats(
     val fecRecovered: Long = 0,
     /** Current mic audio level (RMS, 0-32767). */
     val audioLevel: Int = 0,
+    /** Our current outgoing codec (e.g. "Opus24k"). */
+    val currentCodec: String = "",
+    /** Last seen incoming codec from peers. */
+    val peerCodec: String = "",
+    /** Whether auto quality mode is active. */
+    val autoMode: Boolean = false,
     /** Number of participants in the room. */
     val roomParticipantCount: Int = 0,
     /** Participants in the room (fingerprint + optional alias). */
     val roomParticipants: List<RoomMember> = emptyList(),
+    /** SAS verification code (4-digit, null if not in a call). */
+    val sasCode: Int? = null,
+    /** Incoming call ID (or "relay|room" for CallSetup). */
+    val incomingCallId: String? = null,
+    /** Incoming caller's fingerprint. */
+    val incomingCallerFp: String? = null,
+    /** Incoming caller's alias. */
+    val incomingCallerAlias: String? = null,
 ) {
     /** Human-readable quality label. */
     val qualityLabel: String
@@ -54,7 +68,8 @@ data class CallStats(
                 val o = arr.getJSONObject(i)
                 RoomMember(
                     fingerprint = o.optString("fingerprint", ""),
-                    alias = if (o.isNull("alias")) null else o.optString("alias", null)
+                    alias = if (o.isNull("alias")) null else o.optString("alias", null),
+                    relayLabel = if (o.isNull("relay_label")) null else o.optString("relay_label", null)
                 )
             }
         }
@@ -76,8 +91,15 @@ data class CallStats(
                     underruns = obj.optLong("underruns", 0),
                     fecRecovered = obj.optLong("fec_recovered", 0),
                     audioLevel = obj.optInt("audio_level", 0),
+                    currentCodec = obj.optString("current_codec", ""),
+                    peerCodec = obj.optString("peer_codec", ""),
+                    autoMode = obj.optBoolean("auto_mode", false),
                     roomParticipantCount = obj.optInt("room_participant_count", 0),
-                    roomParticipants = parseParticipants(obj.optJSONArray("room_participants"))
+                    roomParticipants = parseParticipants(obj.optJSONArray("room_participants")),
+                    sasCode = if (obj.has("sas_code")) obj.optInt("sas_code") else null,
+                    incomingCallId = if (obj.isNull("incoming_call_id")) null else obj.optString("incoming_call_id", null),
+                    incomingCallerFp = if (obj.isNull("incoming_caller_fp")) null else obj.optString("incoming_caller_fp", null),
+                    incomingCallerAlias = if (obj.isNull("incoming_caller_alias")) null else obj.optString("incoming_caller_alias", null),
                 )
             } catch (e: Exception) {
                 CallStats()
@@ -88,7 +110,8 @@ data class CallStats(
 
 data class RoomMember(
     val fingerprint: String,
-    val alias: String? = null
+    val alias: String? = null,
+    val relayLabel: String? = null
 ) {
     /** Short display name: alias if set, otherwise first 8 chars of fingerprint. */
     val displayName: String

android/app/src/main/java/com/wzp/engine/SignalManager.kt

@@ -0,0 +1,97 @@
+package com.wzp.engine
+
+import org.json.JSONObject
+
+/**
+ * Persistent signal connection for direct 1:1 calls.
+ * Separate from WzpEngine — survives across calls.
+ *
+ * Lifecycle: connect() → [placeCall/answerCall] → destroy()
+ */
+class SignalManager {
+
+    private var handle: Long = 0L
+
+    val isConnected: Boolean get() = handle != 0L
+
+    /**
+     * Connect to relay and register for direct calls.
+     * MUST be called from a thread with sufficient stack (8MB).
+     * Blocks briefly during QUIC connect + register, then returns.
+     */
+    fun connect(relay: String, seedHex: String): Boolean {
+        if (handle != 0L) return true // already connected
+        handle = nativeSignalConnect(relay, seedHex)
+        return handle != 0L
+    }
+
+    /** Get current signal state as parsed object. Non-blocking. */
+    fun getState(): SignalState {
+        if (handle == 0L) return SignalState()
+        val json = nativeSignalGetState(handle) ?: return SignalState()
+        return try {
+            val obj = JSONObject(json)
+            SignalState(
+                status = obj.optString("status", "idle"),
+                fingerprint = obj.optString("fingerprint", ""),
+                incomingCallId = if (obj.isNull("incoming_call_id")) null else obj.optString("incoming_call_id"),
+                incomingCallerFp = if (obj.isNull("incoming_caller_fp")) null else obj.optString("incoming_caller_fp"),
+                incomingCallerAlias = if (obj.isNull("incoming_caller_alias")) null else obj.optString("incoming_caller_alias"),
+                callSetupRelay = if (obj.isNull("call_setup_relay")) null else obj.optString("call_setup_relay"),
+                callSetupRoom = if (obj.isNull("call_setup_room")) null else obj.optString("call_setup_room"),
+                callSetupId = if (obj.isNull("call_setup_id")) null else obj.optString("call_setup_id"),
+            )
+        } catch (e: Exception) {
+            SignalState()
+        }
+    }
+
+    /** Place a direct call to a target fingerprint. */
+    fun placeCall(targetFp: String): Int {
+        if (handle == 0L) return -1
+        return nativeSignalPlaceCall(handle, targetFp)
+    }
+
+    /** Answer an incoming call. mode: 0=Reject, 1=AcceptTrusted, 2=AcceptGeneric */
+    fun answerCall(callId: String, mode: Int = 2): Int {
+        if (handle == 0L) return -1
+        return nativeSignalAnswerCall(handle, callId, mode)
+    }
+
+    /** Send hangup signal. */
+    fun hangup() {
+        if (handle != 0L) nativeSignalHangup(handle)
+    }
+
+    /** Destroy the signal manager. */
+    fun destroy() {
+        if (handle != 0L) {
+            nativeSignalDestroy(handle)
+            handle = 0L
+        }
+    }
+
+    // JNI native methods
+    private external fun nativeSignalConnect(relay: String, seed: String): Long
+    private external fun nativeSignalGetState(handle: Long): String?
+    private external fun nativeSignalPlaceCall(handle: Long, targetFp: String): Int
+    private external fun nativeSignalAnswerCall(handle: Long, callId: String, mode: Int): Int
+    private external fun nativeSignalHangup(handle: Long)
+    private external fun nativeSignalDestroy(handle: Long)
+
+    companion object {
+        init { System.loadLibrary("wzp_android") }
+    }
+}
+
+/** Signal connection state. */
+data class SignalState(
+    val status: String = "idle",
+    val fingerprint: String = "",
+    val incomingCallId: String? = null,
+    val incomingCallerFp: String? = null,
+    val incomingCallerAlias: String? = null,
+    val callSetupRelay: String? = null,
+    val callSetupRoom: String? = null,
+    val callSetupId: String? = null,
+)

android/app/src/main/java/com/wzp/engine/WzpEngine.kt

@@ -53,6 +53,7 @@ class WzpEngine(private val callback: WzpCallback) {
     }
 
     /** Stop the active call. Safe to call when no call is active. */
+    @Synchronized
     fun stopCall() {
         if (nativeHandle != 0L) {
             nativeStopCall(nativeHandle)
@@ -76,6 +77,7 @@ class WzpEngine(private val callback: WzpCallback) {
      *
      * @return JSON-serialised [CallStats], or `"{}"` if the engine is not initialised.
      */
+    @Synchronized
     fun getStats(): String {
         if (nativeHandle == 0L) return "{}"
         return try {
@@ -95,6 +97,7 @@ class WzpEngine(private val callback: WzpCallback) {
     }
 
     /** Destroy the native engine and free all resources. The instance must not be reused. */
+    @Synchronized
     fun destroy() {
         if (nativeHandle != 0L) {
             nativeDestroy(nativeHandle)
@@ -156,7 +159,22 @@ class WzpEngine(private val callback: WzpCallback) {
     private external fun nativeWriteAudioDirect(handle: Long, buffer: java.nio.ByteBuffer, sampleCount: Int): Int
     private external fun nativeReadAudioDirect(handle: Long, buffer: java.nio.ByteBuffer, maxSamples: Int): Int
     private external fun nativeDestroy(handle: Long)
+
+    companion object {
+        init { System.loadLibrary("wzp_android") }
+
+        /** Get the identity fingerprint for a seed hex. No engine needed. */
+        @JvmStatic
+        private external fun nativeGetFingerprint(seedHex: String): String?
+
+        /** Compute the full identity fingerprint (xxxx:xxxx:...) from a seed hex string. */
+        @JvmStatic
+        fun getFingerprint(seedHex: String): String = nativeGetFingerprint(seedHex) ?: ""
+    }
     private external fun nativePingRelay(handle: Long, relay: String): String?
+    private external fun nativeStartSignaling(handle: Long, relay: String, seed: String, token: String, alias: String): Int
+    private external fun nativePlaceCall(handle: Long, targetFp: String): Int
+    private external fun nativeAnswerCall(handle: Long, callId: String, mode: Int): Int
 
     /**
      * Ping a relay server. Requires engine to be initialized.
@@ -167,11 +185,41 @@ class WzpEngine(private val callback: WzpCallback) {
         return nativePingRelay(nativeHandle, address)
     }
 
-    companion object {
-        init {
-            System.loadLibrary("wzp_android")
+    /**
+     * Start persistent signaling connection for direct 1:1 calls.
+     * The engine registers on the relay and listens for incoming calls.
+     * Call state updates are available via [getStats].
+     *
+     * @return 0 on success, -1 on error
+     */
+    fun startSignaling(relay: String, seed: String = "", token: String = "", alias: String = ""): Int {
+        check(nativeHandle != 0L) { "Engine not initialized" }
+        return nativeStartSignaling(nativeHandle, relay, seed, token, alias)
     }
+
+    /**
+     * Place a direct call to a peer by fingerprint.
+     * Requires [startSignaling] to have been called first.
+     *
+     * @return 0 on success, -1 on error
+     */
+    fun placeCall(targetFingerprint: String): Int {
+        check(nativeHandle != 0L) { "Engine not initialized" }
+        return nativePlaceCall(nativeHandle, targetFingerprint)
     }
+
+    /**
+     * Answer an incoming direct call.
+     *
+     * @param callId The call ID from the incoming call (available in stats.incoming_call_id)
+     * @param mode 0=Reject, 1=AcceptTrusted (P2P in Phase 2), 2=AcceptGeneric (relay-mediated)
+     * @return 0 on success, -1 on error
+     */
+    fun answerCall(callId: String, mode: Int = 2): Int {
+        check(nativeHandle != 0L) { "Engine not initialized" }
+        return nativeAnswerCall(nativeHandle, callId, mode)
+    }
+
 }
 
 /** Integer constants matching the Rust [CallState] enum ordinals. */

android/app/src/main/java/com/wzp/ui/call/CallViewModel.kt

@@ -132,13 +132,143 @@ class CallViewModel : ViewModel(), WzpCallback {
 
     private var statsJob: Job? = null
 
+    // ── Direct calling state ──
+    /** 0=room mode, 1=direct call mode */
+    private val _callMode = MutableStateFlow(0)
+    val callMode: StateFlow<Int> = _callMode.asStateFlow()
+
+    /** Target fingerprint for direct call */
+    private val _targetFingerprint = MutableStateFlow("")
+    val targetFingerprint: StateFlow<String> = _targetFingerprint.asStateFlow()
+
+    /** Signal state string: "idle", "registered", "ringing", "incoming", "setup" */
+    private val _signalState = MutableStateFlow("idle")
+    val signalState: StateFlow<String> = _signalState.asStateFlow()
+
+    /** Incoming call info */
+    private val _incomingCallId = MutableStateFlow<String?>(null)
+    val incomingCallId: StateFlow<String?> = _incomingCallId.asStateFlow()
+
+    private val _incomingCallerFp = MutableStateFlow<String?>(null)
+    val incomingCallerFp: StateFlow<String?> = _incomingCallerFp.asStateFlow()
+
+    private val _incomingCallerAlias = MutableStateFlow<String?>(null)
+    val incomingCallerAlias: StateFlow<String?> = _incomingCallerAlias.asStateFlow()
+
+    /** Separate signal manager (persistent, survives calls) */
+    private var signalManager: com.wzp.engine.SignalManager? = null
+    private var signalPollJob: Job? = null
+
+    fun setCallMode(mode: Int) { _callMode.value = mode }
+    fun setTargetFingerprint(fp: String) { _targetFingerprint.value = fp }
+
+    /** Register on relay for direct calls */
+    fun registerForCalls() {
+        val serverIdx = _selectedServer.value
+        val serverList = _servers.value
+        if (serverIdx >= serverList.size) return
+
+        val relay = serverList[serverIdx].address
+        var seed = _seedHex.value
+        // Generate seed if empty (fresh install or cleared storage)
+        if (seed.isEmpty()) {
+            val newSeed = ByteArray(32).also { java.security.SecureRandom().nextBytes(it) }
+            seed = newSeed.joinToString("") { "%02x".format(it) }
+            _seedHex.value = seed
+            settings?.saveSeedHex(seed)
+            Log.i(TAG, "generated new identity seed")
+        }
+        val resolvedRelay = resolveToIp(relay) ?: relay
+
+        // nativeSignalConnect has JNI overhead — must be on a thread with enough stack.
+        // Dispatchers.IO threads overflow. Use explicit Java Thread.
+        Thread(null, {
+            try {
+                val mgr = com.wzp.engine.SignalManager()
+                val ok = mgr.connect(resolvedRelay, seed)
+                viewModelScope.launch {
+                    if (ok) {
+                        signalManager = mgr
+                        startSignalPolling()
+                    } else {
+                        _errorMessage.value = "Failed to register on relay"
+                    }
+                }
+            } catch (e: Exception) {
+                viewModelScope.launch {
+                    _errorMessage.value = "Register error: ${e.message}"
+                }
+            }
+        }, "wzp-signal-init", 8 * 1024 * 1024).start()
+    }
+
+    /** Poll signal manager state every 500ms */
+    private fun startSignalPolling() {
+        signalPollJob?.cancel()
+        signalPollJob = viewModelScope.launch {
+            while (isActive) {
+                val mgr = signalManager
+                if (mgr != null && mgr.isConnected) {
+                    val state = mgr.getState()
+                    _signalState.value = state.status
+                    _incomingCallId.value = state.incomingCallId
+                    _incomingCallerFp.value = state.incomingCallerFp
+                    _incomingCallerAlias.value = state.incomingCallerAlias
+
+                    // Auto-connect to media room when call is set up
+                    if (state.status == "setup" && state.callSetupRelay != null && state.callSetupRoom != null) {
+                        Log.i(TAG, "CallSetup: connecting to ${state.callSetupRelay} room ${state.callSetupRoom}")
+                        startCallInternal(state.callSetupRelay, state.callSetupRoom)
+                    }
+                }
+                delay(500L)
+            }
+        }
+    }
+
+    private fun stopSignalPolling() {
+        signalPollJob?.cancel()
+        signalPollJob = null
+    }
+
+    /** Place a direct call to the target fingerprint */
+    fun placeDirectCall() {
+        val target = _targetFingerprint.value.trim()
+        if (target.isEmpty()) {
+            _errorMessage.value = "Enter a fingerprint to call"
+            return
+        }
+        signalManager?.placeCall(target)
+    }
+
+    /** Answer an incoming direct call */
+    fun answerIncomingCall(mode: Int = 2) {
+        val callId = _incomingCallId.value ?: return
+        signalManager?.answerCall(callId, mode)
+    }
+
+    /** Reject an incoming direct call */
+    fun rejectIncomingCall() {
+        val callId = _incomingCallId.value ?: return
+        signalManager?.answerCall(callId, 0)
+    }
+
+    /** Hang up direct call — media ends, signal stays alive */
+    fun hangupDirectCall() {
+        signalManager?.hangup()
+        engine?.stopCall()
+        engine?.destroy()
+        engine = null
+        engineInitialized = false
+    }
+
     companion object {
         private const val TAG = "WzpCall"
         val DEFAULT_SERVERS = listOf(
             ServerEntry("172.16.81.175:4433", "LAN (172.16.81.175)"),
             ServerEntry("193.180.213.68:4433", "Pangolin (IP)"),
         )
-        const val DEFAULT_ROOM = "android"
+        const val DEFAULT_ROOM = "general"
     }
 
     fun setContext(context: Context) {
@@ -418,6 +548,45 @@ class CallViewModel : ViewModel(), WzpCallback {
         startCallInternal()
     }
 
+    /** Start a call to a specific relay + room (used by direct call setup). */
+    private fun startCallInternal(relay: String, room: String) {
+        Log.i(TAG, "startCallDirect: relay=$relay room=$room")
+        try {
+            // Don't teardown — keep the signal connection alive
+            engine = WzpEngine(this)
+            engine!!.init()
+            engineInitialized = true
+            _callState.value = 1
+            _errorMessage.value = null
+            try { appContext?.let { CallService.start(it) } } catch (e: Exception) {
+                Log.w(TAG, "service start err: $e")
+            }
+            startStatsPolling()
+            viewModelScope.launch(kotlinx.coroutines.Dispatchers.IO) {
+                try {
+                    val seed = _seedHex.value
+                    val name = _alias.value
+                    val result = engine?.startCall(relay, room, seedHex = seed, alias = name, profile = _codecChoice.value) ?: -1
+                    CallService.onStopFromNotification = { stopCall() }
+                    if (result != 0) {
+                        _callState.value = 0
+                        _errorMessage.value = "Failed to connect to call room (code $result)"
+                        appContext?.let { CallService.stop(it) }
+                    }
+                } catch (e: Exception) {
+                    Log.e(TAG, "startCallDirect error", e)
+                    _callState.value = 0
+                    _errorMessage.value = "Engine error: ${e.message}"
+                    appContext?.let { CallService.stop(it) }
+                }
+            }
+        } catch (e: Exception) {
+            Log.e(TAG, "startCallDirect error", e)
+            _callState.value = 0
+            _errorMessage.value = "Engine error: ${e.message}"
+        }
+    }
+
     private fun startCallInternal() {
         val serverEntry = _servers.value[_selectedServer.value]
         val room = _roomName.value
@@ -568,6 +737,7 @@ class CallViewModel : ViewModel(), WzpCallback {
                         val s = CallStats.fromJson(json)
                         lastCallDuration = s.durationSecs
                         _stats.value = s
+                        // Only update callState from media engine stats (not signal)
                         if (s.state != 0) {
                             _callState.value = s.state
                         }

android/app/src/main/java/com/wzp/ui/call/InCallScreen.kt

@@ -165,7 +165,7 @@ fun InCallScreen(
                     color = Color.White
                 )
                 Text(
-                    text = "ENCRYPTED VOICE",
+                    text = "ENCRYPTED VOICE  \u2022  direct-call-v1",
                     style = MaterialTheme.typography.labelSmall.copy(letterSpacing = 3.sp),
                     color = TextDim
                 )
@@ -217,7 +217,40 @@ fun InCallScreen(
 
                 Spacer(modifier = Modifier.height(12.dp))
 
-                // Room
+                // Mode toggle: Room vs Direct Call
+                val callMode by viewModel.callMode.collectAsState()
+                val signalState by viewModel.signalState.collectAsState()  // "idle"/"registered"/"ringing"/etc
+                val targetFp by viewModel.targetFingerprint.collectAsState()
+                val incomingCallId by viewModel.incomingCallId.collectAsState()
+                val incomingCallerFp by viewModel.incomingCallerFp.collectAsState()
+                val incomingCallerAlias by viewModel.incomingCallerAlias.collectAsState()
+
+                Row(
+                    modifier = Modifier.fillMaxWidth(),
+                    horizontalArrangement = Arrangement.spacedBy(8.dp)
+                ) {
+                    Button(
+                        onClick = { viewModel.setCallMode(0) },
+                        modifier = Modifier.weight(1f).height(36.dp),
+                        shape = RoundedCornerShape(8.dp),
+                        colors = ButtonDefaults.buttonColors(
+                            containerColor = if (callMode == 0) Accent else Color(0xFF333333)
+                        )
+                    ) { Text("Room", color = Color.White, fontSize = 13.sp) }
+                    Button(
+                        onClick = { viewModel.setCallMode(1) },
+                        modifier = Modifier.weight(1f).height(36.dp),
+                        shape = RoundedCornerShape(8.dp),
+                        colors = ButtonDefaults.buttonColors(
+                            containerColor = if (callMode == 1) Accent else Color(0xFF333333)
+                        )
+                    ) { Text("Direct Call", color = Color.White, fontSize = 13.sp) }
+                }
+
+                Spacer(modifier = Modifier.height(12.dp))
+
+                if (callMode == 0) {
+                    // ── Room mode ──
                     SectionLabel("ROOM")
                     OutlinedTextField(
                         value = roomName,
@@ -228,7 +261,6 @@ fun InCallScreen(
 
                     Spacer(modifier = Modifier.height(12.dp))
 
-                // Alias
                     SectionLabel("ALIAS")
                     OutlinedTextField(
                         value = alias,
@@ -239,7 +271,6 @@ fun InCallScreen(
 
                     Spacer(modifier = Modifier.height(12.dp))
 
-                // AEC + Settings
                     Row(
                         verticalAlignment = Alignment.CenterVertically,
                         modifier = Modifier.fillMaxWidth()
@@ -264,7 +295,6 @@ fun InCallScreen(
 
                     Spacer(modifier = Modifier.height(16.dp))
 
-                // Connect button
                     Button(
                         onClick = { viewModel.startCall() },
                         modifier = Modifier.fillMaxWidth().height(48.dp),
@@ -277,6 +307,120 @@ fun InCallScreen(
                             color = Color.White
                         )
                     }
+                } else {
+                    // ── Direct call mode ──
+                    if (signalState == "idle") {
+                        // Not registered yet
+                        SectionLabel("ALIAS")
+                        OutlinedTextField(
+                            value = alias,
+                            onValueChange = { viewModel.setAlias(it) },
+                            singleLine = true,
+                            modifier = Modifier.fillMaxWidth()
+                        )
+
+                        Spacer(modifier = Modifier.height(16.dp))
+
+                        Button(
+                            onClick = { viewModel.registerForCalls() },
+                            modifier = Modifier.fillMaxWidth().height(48.dp),
+                            shape = RoundedCornerShape(8.dp),
+                            colors = ButtonDefaults.buttonColors(containerColor = Color(0xFF2196F3))
+                        ) {
+                            Text(
+                                "Register on Relay",
+                                style = MaterialTheme.typography.titleMedium.copy(fontWeight = FontWeight.Bold),
+                                color = Color.White
+                            )
+                        }
+                    } else if (signalState == "registered" || signalState == "incoming") {
+                        // Registered — show dial pad
+                        Text(
+                            "\u2705 Registered — waiting for calls",
+                            color = Green,
+                            style = MaterialTheme.typography.bodyMedium
+                        )
+
+                        Spacer(modifier = Modifier.height(12.dp))
+
+                        // Incoming call notification
+                        if (incomingCallId != null && incomingCallerFp != null) {
+                            Surface(
+                                color = Color(0xFF1B5E20),
+                                shape = RoundedCornerShape(12.dp),
+                                modifier = Modifier.fillMaxWidth()
+                            ) {
+                                Column(modifier = Modifier.padding(16.dp)) {
+                                    Text(
+                                        "Incoming Call",
+                                        color = Color.White,
+                                        style = MaterialTheme.typography.titleMedium.copy(fontWeight = FontWeight.Bold)
+                                    )
+                                    Text(
+                                        "From: ${incomingCallerAlias ?: incomingCallerFp?.take(16) ?: "unknown"}",
+                                        color = Color.White.copy(alpha = 0.8f),
+                                        style = MaterialTheme.typography.bodySmall
+                                    )
+                                    Spacer(modifier = Modifier.height(12.dp))
+                                    Row(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
+                                        Button(
+                                            onClick = { viewModel.answerIncomingCall(2) },
+                                            colors = ButtonDefaults.buttonColors(containerColor = Green),
+                                            modifier = Modifier.weight(1f)
+                                        ) { Text("Accept", color = Color.White) }
+                                        Button(
+                                            onClick = { viewModel.rejectIncomingCall() },
+                                            colors = ButtonDefaults.buttonColors(containerColor = Red),
+                                            modifier = Modifier.weight(1f)
+                                        ) { Text("Reject", color = Color.White) }
+                                    }
+                                }
+                            }
+                            Spacer(modifier = Modifier.height(12.dp))
+                        }
+
+                        SectionLabel("CALL BY FINGERPRINT")
+                        OutlinedTextField(
+                            value = targetFp,
+                            onValueChange = { viewModel.setTargetFingerprint(it) },
+                            singleLine = true,
+                            placeholder = { Text("Paste fingerprint (xxxx:xxxx:...)") },
+                            modifier = Modifier.fillMaxWidth()
+                        )
+
+                        Spacer(modifier = Modifier.height(16.dp))
+
+                        Button(
+                            onClick = { viewModel.placeDirectCall() },
+                            modifier = Modifier.fillMaxWidth().height(48.dp),
+                            shape = RoundedCornerShape(8.dp),
+                            colors = ButtonDefaults.buttonColors(containerColor = Accent),
+                            enabled = targetFp.isNotBlank()
+                        ) {
+                            Text(
+                                "Call",
+                                style = MaterialTheme.typography.titleMedium.copy(fontWeight = FontWeight.Bold),
+                                color = Color.White
+                            )
+                        }
+                    } else if (signalState == "ringing") {
+                        Text(
+                            "\uD83D\uDD14 Ringing...",
+                            color = Yellow,
+                            style = MaterialTheme.typography.titleMedium,
+                            textAlign = TextAlign.Center,
+                            modifier = Modifier.fillMaxWidth()
+                        )
+                    } else if (signalState == "setup") {
+                        Text(
+                            "Connecting to call...",
+                            color = Accent,
+                            style = MaterialTheme.typography.titleMedium,
+                            textAlign = TextAlign.Center,
+                            modifier = Modifier.fillMaxWidth()
+                        )
+                    }
+                }
 
                 errorMessage?.let { err ->
                     Spacer(modifier = Modifier.height(8.dp))
@@ -285,14 +429,16 @@ fun InCallScreen(
 
                 Spacer(modifier = Modifier.height(20.dp))
 
-                // Identity
-                val fp = if (seedHex.length >= 16) seedHex.take(16) else ""
+                // Identity — compute real fingerprint from seed
+                val fullFp = remember(seedHex) {
+                    if (seedHex.length >= 64) com.wzp.engine.WzpEngine.getFingerprint(seedHex) else ""
+                }
                 Row(verticalAlignment = Alignment.CenterVertically) {
-                    if (fp.isNotEmpty()) {
-                        Identicon(fingerprint = seedHex, size = 28.dp)
+                    if (fullFp.isNotEmpty()) {
+                        Identicon(fingerprint = fullFp, size = 28.dp)
                         Spacer(modifier = Modifier.width(8.dp))
                         CopyableFingerprint(
-                            fingerprint = fp.chunked(4).joinToString(":"),
+                            fingerprint = fullFp,
                             style = MaterialTheme.typography.bodySmall.copy(fontFamily = FontFamily.Monospace),
                             color = TextDim
                         )
@@ -411,7 +557,29 @@ fun InCallScreen(
                         if (stats.roomParticipantCount > 0) {
                             val unique = stats.roomParticipants
                                 .distinctBy { it.fingerprint.ifEmpty { it.displayName } }
-                            unique.forEach { member ->
+                            // Group by relay
+                            val grouped = unique.groupBy { it.relayLabel ?: "This Relay" }
+                            grouped.forEach { (relay, members) ->
+                                // Relay header
+                                val isLocal = relay == "This Relay"
+                                Row(
+                                    verticalAlignment = Alignment.CenterVertically,
+                                    modifier = Modifier.padding(top = 4.dp, bottom = 2.dp)
+                                ) {
+                                    Box(
+                                        modifier = Modifier
+                                            .size(6.dp)
+                                            .clip(CircleShape)
+                                            .background(if (isLocal) Green else Color(0xFF60A5FA))
+                                    )
+                                    Spacer(modifier = Modifier.width(6.dp))
+                                    Text(
+                                        text = relay.uppercase(),
+                                        style = MaterialTheme.typography.labelSmall.copy(letterSpacing = 0.5.sp),
+                                        color = TextDim
+                                    )
+                                }
+                                members.forEach { member ->
                                     Row(
                                         verticalAlignment = Alignment.CenterVertically,
                                         modifier = Modifier.padding(vertical = 4.dp)
@@ -440,6 +608,7 @@ fun InCallScreen(
                                         }
                                     }
                                 }
+                            }
                         } else {
                             Text(
                                 text = "Waiting for participants...",
@@ -463,7 +632,51 @@ fun InCallScreen(
 
                 Spacer(modifier = Modifier.height(12.dp))
 
-                // Stats
+                // Codec + Stats
+                if (stats.currentCodec.isNotEmpty()) {
+                    val codecLabel = formatCodecName(stats.currentCodec)
+                    val peerLabel = if (stats.peerCodec.isNotEmpty()) formatCodecName(stats.peerCodec) else null
+                    val autoTag = if (stats.autoMode) " [Auto]" else ""
+                    Row(
+                        modifier = Modifier.fillMaxWidth(),
+                        horizontalArrangement = Arrangement.Center,
+                        verticalAlignment = Alignment.CenterVertically
+                    ) {
+                        // Our codec badge
+                        Surface(
+                            shape = RoundedCornerShape(4.dp),
+                            color = codecColor(stats.currentCodec)
+                        ) {
+                            Text(
+                                text = "TX $codecLabel$autoTag",
+                                modifier = Modifier.padding(horizontal = 6.dp, vertical = 2.dp),
+                                style = MaterialTheme.typography.labelSmall.copy(
+                                    fontFamily = FontFamily.Monospace,
+                                    fontSize = 10.sp
+                                ),
+                                color = Color.White
+                            )
+                        }
+                        if (peerLabel != null) {
+                            Spacer(modifier = Modifier.width(6.dp))
+                            Surface(
+                                shape = RoundedCornerShape(4.dp),
+                                color = codecColor(stats.peerCodec)
+                            ) {
+                                Text(
+                                    text = "RX $peerLabel",
+                                    modifier = Modifier.padding(horizontal = 6.dp, vertical = 2.dp),
+                                    style = MaterialTheme.typography.labelSmall.copy(
+                                        fontFamily = FontFamily.Monospace,
+                                        fontSize = 10.sp
+                                    ),
+                                    color = Color.White
+                                )
+                            }
+                        }
+                    }
+                    Spacer(modifier = Modifier.height(4.dp))
+                }
                 Text(
                     text = "TX: ${stats.framesEncoded} | RX: ${stats.framesDecoded}",
                     style = MaterialTheme.typography.labelSmall.copy(fontFamily = FontFamily.Monospace),
@@ -825,3 +1038,25 @@ private fun DebugReportCard(
         }
     }
 }
+
+/** Map Rust CodecId debug name to a human-readable label. */
+private fun formatCodecName(codecId: String): String = when (codecId) {
+    "Opus64k" -> "Opus 64k"
+    "Opus48k" -> "Opus 48k"
+    "Opus32k" -> "Opus 32k"
+    "Opus24k" -> "Opus 24k"
+    "Opus16k" -> "Opus 16k"
+    "Opus6k" -> "Opus 6k"
+    "Codec2_3200" -> "C2 3.2k"
+    "Codec2_1200" -> "C2 1.2k"
+    else -> codecId
+}
+
+/** Color-code codec badges by quality tier. */
+private fun codecColor(codecId: String): Color = when (codecId) {
+    "Opus64k", "Opus48k", "Opus32k" -> Color(0xFF0D6EFD) // blue — studio
+    "Opus24k", "Opus16k" -> Color(0xFF198754) // green — good
+    "Opus6k" -> Color(0xFFCC8800) // amber — degraded
+    "Codec2_3200", "Codec2_1200" -> Color(0xFFDC3545) // red — catastrophic
+    else -> Color(0xFF6C757D) // gray
+}

crates/wzp-android/src/commands.rs

@@ -12,4 +12,13 @@ pub enum EngineCommand {
     ForceProfile(QualityProfile),
     /// Stop the call and shut down the engine.
     Stop,
+    /// Place a direct call to a fingerprint (requires signal connection).
+    PlaceCall { target_fingerprint: String },
+    /// Answer an incoming direct call.
+    AnswerCall {
+        call_id: String,
+        accept_mode: wzp_proto::CallAcceptMode,
+    },
+    /// Reject an incoming direct call.
+    RejectCall { call_id: String },
 }

crates/wzp-android/src/engine.rs

@@ -9,7 +9,7 @@
 //! and AudioTrack. PCM samples are transferred through lock-free ring buffers.
 
 use std::net::SocketAddr;
-use std::sync::atomic::{AtomicBool, AtomicU16, AtomicU32, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU8, AtomicU16, AtomicU32, Ordering};
 use std::sync::{Arc, Mutex};
 use std::time::Instant;
 
@@ -19,8 +19,8 @@ use wzp_codec::agc::AutoGainControl;
 use wzp_crypto::{KeyExchange, WarzoneKeyExchange};
 use wzp_fec::{RaptorQFecDecoder, RaptorQFecEncoder};
 use wzp_proto::{
-    AudioDecoder, AudioEncoder, CodecId, FecDecoder, FecEncoder,
-    MediaHeader, MediaPacket, MediaTransport, QualityProfile, SignalMessage,
+    AdaptiveQualityController, AudioDecoder, AudioEncoder, CodecId, FecDecoder, FecEncoder,
+    MediaHeader, MediaPacket, MediaTransport, QualityController, QualityProfile, SignalMessage,
 };
 
 use crate::audio_ring::AudioRing;
@@ -30,6 +30,27 @@ use crate::stats::{CallState, CallStats};
 /// Max frame size at 48kHz mono (40ms = 1920 samples, for Codec2/Opus6k).
 const MAX_FRAME_SAMPLES: usize = 1920;
 
+/// Sentinel value: no profile change pending.
+const PROFILE_NO_CHANGE: u8 = 0xFF;
+
+/// All quality profiles in index order, for AtomicU8-based signaling.
+const PROFILES: [QualityProfile; 6] = [
+    QualityProfile::STUDIO_64K,   // 0
+    QualityProfile::STUDIO_48K,   // 1
+    QualityProfile::STUDIO_32K,   // 2
+    QualityProfile::GOOD,         // 3
+    QualityProfile::DEGRADED,     // 4
+    QualityProfile::CATASTROPHIC, // 5
+];
+
+fn profile_to_index(p: &QualityProfile) -> u8 {
+    PROFILES.iter().position(|pp| pp.codec == p.codec).map(|i| i as u8).unwrap_or(3)
+}
+
+fn index_to_profile(idx: u8) -> Option<QualityProfile> {
+    PROFILES.get(idx as usize).copied()
+}
+
 /// Compute frame samples at 48kHz for a given profile.
 fn frame_samples_for(profile: &QualityProfile) -> usize {
     (profile.frame_duration_ms as usize) * 48 // 48000 / 1000
@@ -180,7 +201,6 @@ impl WzpEngine {
     /// Returns JSON `{"rtt_ms":N,"server_fingerprint":"hex"}` or error.
     pub fn ping_relay(&self, address: &str) -> Result<String, anyhow::Error> {
         let addr: SocketAddr = address.parse()?;
-        let _ = rustls::crypto::ring::default_provider().install_default();
 
         let rt = tokio::runtime::Builder::new_current_thread()
             .enable_all()
@@ -223,6 +243,9 @@ impl WzpEngine {
         result
     }
 
+    /// Start persistent signaling connection for direct calls.
+    // Signal methods (start_signaling, place_call, answer_call) moved to signal_mgr.rs
+
     pub fn set_mute(&self, muted: bool) {
         self.state.muted.store(muted, Ordering::Relaxed);
     }
@@ -285,7 +308,6 @@ async fn run_call(
     alias: Option<&str>,
     state: Arc<EngineState>,
 ) -> Result<(), anyhow::Error> {
-    let _ = rustls::crypto::ring::default_provider().install_default();
 
     let bind_addr: SocketAddr = "0.0.0.0:0".parse().unwrap();
     let endpoint = wzp_transport::create_endpoint(bind_addr, None)?;
@@ -371,7 +393,7 @@ async fn run_call(
     let mut capture_agc = AutoGainControl::new();
     let mut playout_agc = AutoGainControl::new();
 
-    let frame_samples = frame_samples_for(&profile);
+    let mut frame_samples = frame_samples_for(&profile);
     info!(
         codec = ?profile.codec,
         fec_ratio = profile.fec_ratio,
@@ -381,15 +403,27 @@ async fn run_call(
         "codec + FEC + AGC initialized"
     );
 
+    {
+        let mut stats = state.stats.lock().unwrap();
+        stats.current_codec = format!("{:?}", profile.codec);
+        stats.auto_mode = auto_profile;
+    }
+
     let seq = AtomicU16::new(0);
     let ts = AtomicU32::new(0);
     let transport_recv = transport.clone();
 
+    // Adaptive quality: shared AtomicU8 between recv task (writer) and send task (reader).
+    // 0xFF = no change pending, 0-5 = index into PROFILES array.
+    let pending_profile = Arc::new(AtomicU8::new(PROFILE_NO_CHANGE));
+    let pending_profile_recv = pending_profile.clone();
+
     // Pre-allocate buffers (sized for current profile)
     let mut capture_buf = vec![0i16; frame_samples];
     let mut encode_buf = vec![0u8; encoder.max_frame_bytes()];
     let mut frame_in_block: u8 = 0;
     let mut block_id: u8 = 0;
+    let mut current_profile = profile;
 
     // Send task: capture ring → Opus encode → FEC → MediaPackets
     //
@@ -415,6 +449,39 @@ async fn run_call(
                 break;
             }
 
+            // Check for adaptive profile switch from recv task
+            if auto_profile {
+                let p = pending_profile.swap(PROFILE_NO_CHANGE, Ordering::Acquire);
+                if p != PROFILE_NO_CHANGE {
+                    if let Some(new_profile) = index_to_profile(p) {
+                        info!(
+                            from = ?current_profile.codec,
+                            to = ?new_profile.codec,
+                            "auto: switching encoder profile"
+                        );
+                        if let Err(e) = encoder.set_profile(new_profile) {
+                            warn!("encoder set_profile failed: {e}");
+                        } else {
+                            fec_enc = wzp_fec::create_encoder(&new_profile);
+                            current_profile = new_profile;
+                            let new_frame_samples = frame_samples_for(&new_profile);
+                            if new_frame_samples != frame_samples {
+                                frame_samples = new_frame_samples;
+                                capture_buf.resize(frame_samples, 0);
+                            }
+                            encode_buf.resize(encoder.max_frame_bytes(), 0);
+                            // Reset FEC block state for clean switch
+                            frame_in_block = 0;
+                            block_id = block_id.wrapping_add(1);
+                            // Update stats with new codec
+                            if let Ok(mut stats) = state.stats.lock() {
+                                stats.current_codec = format!("{:?}", new_profile.codec);
+                            }
+                        }
+                    }
+                }
+            }
+
             let avail = state.capture_ring.available();
             if avail < frame_samples {
                 tokio::time::sleep(std::time::Duration::from_millis(5)).await;
@@ -457,9 +524,9 @@ async fn run_call(
                 header: MediaHeader {
                     version: 0,
                     is_repair: false,
-                    codec_id: profile.codec,
+                    codec_id: current_profile.codec,
                     has_quality_report: false,
-                    fec_ratio_encoded: MediaHeader::encode_fec_ratio(profile.fec_ratio),
+                    fec_ratio_encoded: MediaHeader::encode_fec_ratio(current_profile.fec_ratio),
                     seq: s,
                     timestamp: t,
                     fec_block: block_id,
@@ -501,8 +568,8 @@ async fn run_call(
             frame_in_block += 1;
 
             // When block is full, generate repair packets
-            if frame_in_block >= profile.frames_per_block {
-                match fec_enc.generate_repair(profile.fec_ratio) {
+            if frame_in_block >= current_profile.frames_per_block {
+                match fec_enc.generate_repair(current_profile.fec_ratio) {
                     Ok(repairs) => {
                         let repair_count = repairs.len();
                         for (sym_idx, repair_data) in repairs {
@@ -511,10 +578,10 @@ async fn run_call(
                                 header: MediaHeader {
                                     version: 0,
                                     is_repair: true,
-                                    codec_id: profile.codec,
+                                    codec_id: current_profile.codec,
                                     has_quality_report: false,
                                     fec_ratio_encoded: MediaHeader::encode_fec_ratio(
-                                        profile.fec_ratio,
+                                        current_profile.fec_ratio,
                                     ),
                                     seq: rs,
                                     timestamp: t,
@@ -537,7 +604,7 @@ async fn run_call(
                             info!(
                                 block_id,
                                 repair_count,
-                                fec_ratio = profile.fec_ratio,
+                                fec_ratio = current_profile.fec_ratio,
                                 "FEC block complete"
                             );
                         }
@@ -590,6 +657,8 @@ async fn run_call(
         let mut last_recv_instant = Instant::now();
         let mut max_recv_gap_ms: u64 = 0;
         let mut last_stats_log = Instant::now();
+        let mut quality_ctrl = AdaptiveQualityController::new();
+        let mut last_peer_codec: Option<CodecId> = None;
         info!("recv task started (Opus + RaptorQ FEC)");
         loop {
             if !state.running.load(Ordering::Relaxed) {
@@ -612,6 +681,23 @@ async fn run_call(
                         );
                     }
 
+                    // Adaptive quality: ingest quality reports from relay
+                    if auto_profile {
+                        if let Some(ref qr) = pkt.quality_report {
+                            if let Some(new_profile) = quality_ctrl.observe(qr) {
+                                let idx = profile_to_index(&new_profile);
+                                info!(
+                                    loss = qr.loss_percent(),
+                                    rtt = qr.rtt_ms(),
+                                    tier = ?quality_ctrl.tier(),
+                                    to = ?new_profile.codec,
+                                    "auto: quality adapter recommends switch"
+                                );
+                                pending_profile_recv.store(idx, Ordering::Release);
+                            }
+                        }
+                    }
+
                     let is_repair = pkt.header.is_repair;
                     let pkt_block = pkt.header.fec_block;
                     let pkt_symbol = pkt.header.fec_symbol;
@@ -646,6 +732,13 @@ async fn run_call(
                             info!(from = ?decoder.codec_id(), to = ?pkt.header.codec_id, "recv: switching decoder");
                             let _ = decoder.set_profile(switch_profile);
                         }
+                        // Track peer codec for UI display
+                        if last_peer_codec != Some(pkt.header.codec_id) {
+                            last_peer_codec = Some(pkt.header.codec_id);
+                            if let Ok(mut stats) = state.stats.lock() {
+                                stats.peer_codec = format!("{:?}", pkt.header.codec_id);
+                            }
+                        }
                         match decoder.decode(&pkt.payload, &mut decode_buf) {
                             Ok(samples) => {
                                 playout_agc.process_frame(&mut decode_buf[..samples]);
@@ -760,6 +853,7 @@ async fn run_call(
                         .map(|p| crate::stats::RoomMember {
                             fingerprint: p.fingerprint.clone(),
                             alias: p.alias.clone(),
+                            relay_label: p.relay_label.clone(),
                         })
                         .collect();
                     let mut stats = state_signal.stats.lock().unwrap();

crates/wzp-android/src/jni_bridge.rs

@@ -77,6 +77,9 @@ pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeInit(
 ) -> jlong {
     let result = panic::catch_unwind(|| {
         init_logging();
+        // Install rustls crypto provider ONCE on the main thread.
+        // Must not be called per-thread — conflicts with Android's system libcrypto.so TLS keys.
+        let _ = rustls::crypto::ring::default_provider().install_default();
         let handle = Box::new(EngineHandle {
             engine: WzpEngine::new(),
         });
@@ -359,3 +362,150 @@ pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativePingRelay<'a>(
         .map(|s| s.into_raw())
         .unwrap_or(JObject::null().into_raw())
 }
+
+/// Get the identity fingerprint for a seed hex string.
+/// Returns the full fingerprint (xxxx:xxxx:...) or empty string on error.
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeGetFingerprint<'a>(
+    mut env: JNIEnv<'a>,
+    _class: JClass,
+    seed_hex_j: JString,
+) -> jstring {
+    let seed_hex: String = env.get_string(&seed_hex_j).map(|s| s.into()).unwrap_or_default();
+    let fp = if seed_hex.is_empty() {
+        String::new()
+    } else {
+        match wzp_crypto::Seed::from_hex(&seed_hex) {
+            Ok(seed) => {
+                let id = seed.derive_identity();
+                id.public_identity().fingerprint.to_string()
+            }
+            Err(_) => String::new(),
+        }
+    };
+    env.new_string(&fp)
+        .map(|s| s.into_raw())
+        .unwrap_or(JObject::null().into_raw())
+}
+
+// ── Direct calling JNI functions ──
+
+// ── SignalManager JNI functions ──
+
+/// Opaque handle for SignalManager (separate from EngineHandle).
+struct SignalHandle {
+    mgr: crate::signal_mgr::SignalManager,
+}
+
+unsafe fn signal_ref(handle: jlong) -> &'static SignalHandle {
+    unsafe { &*(handle as *const SignalHandle) }
+}
+
+/// Connect to relay for signaling. Returns handle (jlong) or 0 on error.
+/// Blocks up to 10s waiting for the internal signal thread to connect.
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_SignalManager_nativeSignalConnect<'a>(
+    mut env: JNIEnv<'a>,
+    _class: JClass,
+    relay_j: JString,
+    seed_j: JString,
+) -> jlong {
+    info!("nativeSignalConnect: entered");
+    let relay: String = env.get_string(&relay_j).map(|s| s.into()).unwrap_or_default();
+    let seed: String = env.get_string(&seed_j).map(|s| s.into()).unwrap_or_default();
+    info!(relay = %relay, seed_len = seed.len(), "nativeSignalConnect: parsed strings");
+
+    // start() spawns an internal thread (connect+register+recv, ONE runtime, never dropped).
+    // Blocks up to 10s waiting for the connect+register to complete.
+    match crate::signal_mgr::SignalManager::start(&relay, &seed) {
+        Ok(mgr) => {
+            let handle = Box::new(SignalHandle { mgr });
+            Box::into_raw(handle) as jlong
+        }
+        Err(e) => {
+            error!("signal connect failed: {e}");
+            0
+        }
+    }
+}
+
+/// Get signal state as JSON string.
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_SignalManager_nativeSignalGetState<'a>(
+    mut env: JNIEnv<'a>,
+    _class: JClass,
+    handle: jlong,
+) -> jstring {
+    if handle == 0 { return JObject::null().into_raw(); }
+    let h = signal_ref(handle);
+    let json = h.mgr.get_state_json();
+    env.new_string(&json)
+        .map(|s| s.into_raw())
+        .unwrap_or(JObject::null().into_raw())
+}
+
+/// Place a direct call.
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_SignalManager_nativeSignalPlaceCall<'a>(
+    mut env: JNIEnv<'a>,
+    _class: JClass,
+    handle: jlong,
+    target_j: JString,
+) -> jint {
+    if handle == 0 { return -1; }
+    let h = signal_ref(handle);
+    let target: String = env.get_string(&target_j).map(|s| s.into()).unwrap_or_default();
+    match h.mgr.place_call(&target) {
+        Ok(()) => 0,
+        Err(e) => { error!("place_call: {e}"); -1 }
+    }
+}
+
+/// Answer an incoming call.
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_SignalManager_nativeSignalAnswerCall<'a>(
+    mut env: JNIEnv<'a>,
+    _class: JClass,
+    handle: jlong,
+    call_id_j: JString,
+    mode: jint,
+) -> jint {
+    if handle == 0 { return -1; }
+    let h = signal_ref(handle);
+    let call_id: String = env.get_string(&call_id_j).map(|s| s.into()).unwrap_or_default();
+    let accept_mode = match mode {
+        0 => wzp_proto::CallAcceptMode::Reject,
+        1 => wzp_proto::CallAcceptMode::AcceptTrusted,
+        _ => wzp_proto::CallAcceptMode::AcceptGeneric,
+    };
+    match h.mgr.answer_call(&call_id, accept_mode) {
+        Ok(()) => 0,
+        Err(e) => { error!("answer_call: {e}"); -1 }
+    }
+}
+
+/// Send hangup signal.
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_SignalManager_nativeSignalHangup(
+    _env: JNIEnv,
+    _class: JClass,
+    handle: jlong,
+) {
+    if handle == 0 { return; }
+    let h = signal_ref(handle);
+    h.mgr.hangup();
+}
+
+/// Destroy the signal manager and free resources.
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_SignalManager_nativeSignalDestroy(
+    _env: JNIEnv,
+    _class: JClass,
+    handle: jlong,
+) {
+    if handle == 0 { return; }
+    let h = signal_ref(handle);
+    h.mgr.stop();
+    // Reclaim the Box
+    let _ = unsafe { Box::from_raw(handle as *mut SignalHandle) };
+}

crates/wzp-android/src/lib.rs

@@ -14,5 +14,6 @@ pub mod audio_ring;
 pub mod commands;
 pub mod engine;
 pub mod pipeline;
+pub mod signal_mgr;
 pub mod stats;
 pub mod jni_bridge;

crates/wzp-android/src/signal_mgr.rs

@@ -0,0 +1,288 @@
+//! Persistent signal connection manager for direct 1:1 calls.
+//!
+//! Separate from the media engine — survives across calls.
+//! Connects to relay via `_signal` SNI, registers presence,
+//! and handles call signaling (offer/answer/setup/hangup).
+
+use std::net::SocketAddr;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+
+use tracing::{error, info, warn};
+use wzp_proto::{MediaTransport, SignalMessage};
+
+/// Signal connection status.
+#[derive(Clone, Debug, Default, serde::Serialize)]
+pub struct SignalState {
+    pub status: String, // "idle", "registered", "ringing", "incoming", "setup"
+    pub fingerprint: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub incoming_call_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub incoming_caller_fp: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub incoming_caller_alias: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub call_setup_relay: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub call_setup_room: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub call_setup_id: Option<String>,
+}
+
+/// Manages a persistent `_signal` QUIC connection to a relay.
+pub struct SignalManager {
+    transport: Arc<wzp_transport::QuinnTransport>,
+    state: Arc<Mutex<SignalState>>,
+    running: Arc<AtomicBool>,
+}
+
+impl SignalManager {
+    /// Create SignalManager and start connect+register+recv on a background thread.
+    /// Returns immediately. The internal thread runs forever.
+    /// CRITICAL: tokio runtime must never be dropped on Android (libcrypto TLS conflict).
+    pub fn start(relay_addr: &str, seed_hex: &str) -> Result<Self, anyhow::Error> {
+        let addr: SocketAddr = relay_addr.parse()?;
+        let seed = if seed_hex.is_empty() {
+            wzp_crypto::Seed::generate()
+        } else {
+            wzp_crypto::Seed::from_hex(seed_hex).map_err(|e| anyhow::anyhow!(e))?
+        };
+        let identity = seed.derive_identity();
+        let pub_id = identity.public_identity();
+        let identity_pub = *pub_id.signing.as_bytes();
+        let fp = pub_id.fingerprint.to_string();
+
+        let state = Arc::new(Mutex::new(SignalState {
+            status: "connecting".into(),
+            fingerprint: fp.clone(),
+            ..Default::default()
+        }));
+        let running = Arc::new(AtomicBool::new(true));
+
+        // Channel to receive transport after connect succeeds
+        let (transport_tx, transport_rx) = std::sync::mpsc::channel();
+
+        let bg_state = Arc::clone(&state);
+        let bg_running = Arc::clone(&running);
+        let ret_state = Arc::clone(&state);
+        let ret_running = Arc::clone(&running);
+
+        // ONE thread, ONE runtime, NEVER dropped.
+        // Connect + register + recv loop all happen here.
+        std::thread::Builder::new()
+            .name("wzp-signal".into())
+            .stack_size(4 * 1024 * 1024)
+            .spawn(move || {
+                let rt = tokio::runtime::Builder::new_current_thread()
+                    .enable_all()
+                    .build()
+                    .expect("tokio runtime");
+
+                rt.block_on(async move {
+                    info!(fingerprint = %fp, relay = %addr, "signal: connecting");
+
+                    let bind: SocketAddr = "0.0.0.0:0".parse().unwrap();
+                    let endpoint = match wzp_transport::create_endpoint(bind, None) {
+                        Ok(e) => e,
+                        Err(e) => {
+                            error!("signal endpoint: {e}");
+                            bg_state.lock().unwrap().status = "idle".into();
+                            return;
+                        }
+                    };
+                    let client_cfg = wzp_transport::client_config();
+                    let conn = match wzp_transport::connect(&endpoint, addr, "_signal", client_cfg).await {
+                        Ok(c) => c,
+                        Err(e) => {
+                            error!("signal connect: {e}");
+                            bg_state.lock().unwrap().status = "idle".into();
+                            return;
+                        }
+                    };
+                    let transport = Arc::new(wzp_transport::QuinnTransport::new(conn));
+
+                    // Register
+                    if let Err(e) = transport.send_signal(&SignalMessage::RegisterPresence {
+                        identity_pub, signature: vec![], alias: None,
+                    }).await {
+                        error!("signal register: {e}");
+                        bg_state.lock().unwrap().status = "idle".into();
+                        return;
+                    }
+
+                    match transport.recv_signal().await {
+                        Ok(Some(SignalMessage::RegisterPresenceAck { success: true, .. })) => {
+                            info!(fingerprint = %fp, "signal: registered");
+                            bg_state.lock().unwrap().status = "registered".into();
+                            // Send transport to caller
+                            let _ = transport_tx.send(transport.clone());
+                        }
+                        other => {
+                            error!("signal registration failed: {other:?}");
+                            bg_state.lock().unwrap().status = "idle".into();
+                            return;
+                        }
+                    }
+
+                    // Recv loop — runs forever
+            loop {
+                if !running.load(Ordering::Relaxed) { break; }
+
+                match transport.recv_signal().await {
+                    Ok(Some(SignalMessage::CallRinging { call_id })) => {
+                        info!(call_id = %call_id, "signal: ringing");
+                        let mut s = state.lock().unwrap();
+                        s.status = "ringing".into();
+                    }
+                    Ok(Some(SignalMessage::DirectCallOffer { caller_fingerprint, caller_alias, call_id, .. })) => {
+                        info!(from = %caller_fingerprint, call_id = %call_id, "signal: incoming call");
+                        let mut s = state.lock().unwrap();
+                        s.status = "incoming".into();
+                        s.incoming_call_id = Some(call_id);
+                        s.incoming_caller_fp = Some(caller_fingerprint);
+                        s.incoming_caller_alias = caller_alias;
+                    }
+                    Ok(Some(SignalMessage::DirectCallAnswer { call_id, accept_mode, .. })) => {
+                        info!(call_id = %call_id, mode = ?accept_mode, "signal: call answered");
+                    }
+                    Ok(Some(SignalMessage::CallSetup { call_id, room, relay_addr })) => {
+                        info!(call_id = %call_id, room = %room, relay = %relay_addr, "signal: call setup");
+                        let mut s = state.lock().unwrap();
+                        s.status = "setup".into();
+                        s.call_setup_relay = Some(relay_addr);
+                        s.call_setup_room = Some(room);
+                        s.call_setup_id = Some(call_id);
+                    }
+                    Ok(Some(SignalMessage::Hangup { reason })) => {
+                        info!(reason = ?reason, "signal: hangup");
+                        let mut s = state.lock().unwrap();
+                        s.status = "registered".into();
+                        s.incoming_call_id = None;
+                        s.incoming_caller_fp = None;
+                        s.incoming_caller_alias = None;
+                        s.call_setup_relay = None;
+                        s.call_setup_room = None;
+                        s.call_setup_id = None;
+                    }
+                    Ok(Some(_)) => {}
+                    Ok(None) => {
+                        info!("signal: connection closed");
+                        break;
+                    }
+                    Err(e) => {
+                        error!("signal recv error: {e}");
+                        break;
+                    }
+                }
+            }
+
+            bg_state.lock().unwrap().status = "idle".into();
+                }); // block_on
+
+                // Runtime intentionally NOT dropped — lives until thread exits.
+                // This prevents ring/libcrypto TLS cleanup conflict on Android.
+                // The thread is parked here forever (block_on returned = connection lost).
+                std::thread::park();
+            })?; // thread spawn
+
+        // Wait for transport (up to 10s)
+        let transport = transport_rx.recv_timeout(std::time::Duration::from_secs(10))
+            .map_err(|_| anyhow::anyhow!("signal connect timeout — check relay address"))?;
+
+        Ok(Self { transport, state: ret_state, running: ret_running })
+    }
+
+    /// Get current state (non-blocking).
+    pub fn get_state(&self) -> SignalState {
+        self.state.lock().unwrap().clone()
+    }
+
+    /// Get state as JSON string.
+    pub fn get_state_json(&self) -> String {
+        serde_json::to_string(&self.get_state()).unwrap_or_else(|_| "{}".into())
+    }
+
+    /// Place a direct call.
+    pub fn place_call(&self, target_fp: &str) -> Result<(), anyhow::Error> {
+        let fp = self.state.lock().unwrap().fingerprint.clone();
+        let target = target_fp.to_string();
+        let call_id = format!("{:016x}", std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos());
+        let transport = self.transport.clone();
+
+        // Send on a small thread (async send needs a runtime)
+        std::thread::Builder::new()
+            .name("wzp-call-send".into())
+            .spawn(move || {
+                let rt = tokio::runtime::Builder::new_current_thread()
+                    .enable_all().build().expect("rt");
+                rt.block_on(async {
+                    let _ = transport.send_signal(&SignalMessage::DirectCallOffer {
+                        caller_fingerprint: fp,
+                        caller_alias: None,
+                        target_fingerprint: target,
+                        call_id,
+                        identity_pub: [0u8; 32],
+                        ephemeral_pub: [0u8; 32],
+                        signature: vec![],
+                        supported_profiles: vec![wzp_proto::QualityProfile::GOOD],
+                    }).await;
+                });
+            })?;
+        Ok(())
+    }
+
+    /// Answer an incoming call.
+    pub fn answer_call(&self, call_id: &str, mode: wzp_proto::CallAcceptMode) -> Result<(), anyhow::Error> {
+        let call_id = call_id.to_string();
+        let transport = self.transport.clone();
+
+        std::thread::Builder::new()
+            .name("wzp-answer-send".into())
+            .spawn(move || {
+                let rt = tokio::runtime::Builder::new_current_thread()
+                    .enable_all().build().expect("rt");
+                rt.block_on(async {
+                    let _ = transport.send_signal(&SignalMessage::DirectCallAnswer {
+                        call_id,
+                        accept_mode: mode,
+                        identity_pub: None,
+                        ephemeral_pub: None,
+                        signature: None,
+                        chosen_profile: Some(wzp_proto::QualityProfile::GOOD),
+                    }).await;
+                });
+            })?;
+        Ok(())
+    }
+
+    /// Send hangup.
+    pub fn hangup(&self) {
+        let transport = self.transport.clone();
+        let state = self.state.clone();
+        std::thread::spawn(move || {
+            let rt = tokio::runtime::Builder::new_current_thread()
+                .enable_all().build().expect("rt");
+            rt.block_on(async {
+                let _ = transport.send_signal(&SignalMessage::Hangup {
+                    reason: wzp_proto::HangupReason::Normal,
+                }).await;
+            });
+            let mut s = state.lock().unwrap();
+            s.status = "registered".into();
+            s.incoming_call_id = None;
+            s.incoming_caller_fp = None;
+            s.incoming_caller_alias = None;
+            s.call_setup_relay = None;
+            s.call_setup_room = None;
+            s.call_setup_id = None;
+        });
+    }
+
+    /// Stop the signal connection.
+    pub fn stop(&self) {
+        self.running.store(false, Ordering::Release);
+        self.transport.connection().close(0u32.into(), b"shutdown");
+    }
+}

crates/wzp-android/src/stats.rs

@@ -11,6 +11,12 @@ pub enum CallState {
     Active,
     Reconnecting,
     Closed,
+    /// Connected to relay signal channel, registered for direct calls.
+    Registered,
+    /// Outgoing call ringing on callee's side.
+    Ringing,
+    /// Incoming call received, waiting for user to accept/reject.
+    IncomingCall,
 }
 
 impl serde::Serialize for CallState {
@@ -21,6 +27,9 @@ impl serde::Serialize for CallState {
             CallState::Active => 2,
             CallState::Reconnecting => 3,
             CallState::Closed => 4,
+            CallState::Registered => 5,
+            CallState::Ringing => 6,
+            CallState::IncomingCall => 7,
         };
         serializer.serialize_u8(n)
     }
@@ -59,10 +68,28 @@ pub struct CallStats {
     pub capture_overflows: u64,
     /// Current mic audio level (RMS of i16 samples, 0-32767).
     pub audio_level: u32,
+    /// Our current outgoing codec name (e.g. "Opus24k", "Codec2_1200").
+    pub current_codec: String,
+    /// Last seen incoming codec from other participants.
+    pub peer_codec: String,
+    /// Whether auto quality mode is active.
+    pub auto_mode: bool,
     /// Number of participants in the room (from last RoomUpdate).
     pub room_participant_count: u32,
     /// Participant list (fingerprint + optional alias) serialized as JSON array.
     pub room_participants: Vec<RoomMember>,
+    /// SAS code for verbal verification (None if not in a call).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub sas_code: Option<u32>,
+    /// Incoming call info (present when state == IncomingCall).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub incoming_call_id: Option<String>,
+    /// Fingerprint of the caller (present when state == IncomingCall).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub incoming_caller_fp: Option<String>,
+    /// Alias of the caller (present when state == IncomingCall).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub incoming_caller_alias: Option<String>,
 }
 
 /// A room member entry, serialized into the stats JSON.
@@ -70,4 +97,5 @@ pub struct CallStats {
 pub struct RoomMember {
     pub fingerprint: String,
     pub alias: Option<String>,
+    pub relay_label: Option<String>,
 }

crates/wzp-client/src/cli.rs

@@ -47,6 +47,11 @@ struct CliArgs {
     room: Option<String>,
     token: Option<String>,
     _metrics_file: Option<String>,
+    version_check: bool,
+    /// Connect to relay for persistent signaling (direct calls).
+    signal: bool,
+    /// Place a direct call to a fingerprint (requires --signal).
+    call_target: Option<String>,
 }
 
 impl CliArgs {
@@ -88,12 +93,20 @@ fn parse_args() -> CliArgs {
     let mut room = None;
     let mut token = None;
     let mut metrics_file = None;
+    let mut version_check = false;
     let mut relay_str = None;
+    let mut signal = false;
+    let mut call_target = None;
 
     let mut i = 1;
     while i < args.len() {
         match args[i].as_str() {
             "--live" => live = true,
+            "--signal" => signal = true,
+            "--call" => {
+                i += 1;
+                call_target = Some(args.get(i).expect("--call requires a fingerprint").to_string());
+            }
             "--send-tone" => {
                 i += 1;
                 send_tone_secs = Some(
@@ -169,6 +182,7 @@ fn parse_args() -> CliArgs {
                 );
             }
             "--sweep" => sweep = true,
+            "--version-check" => { version_check = true; }
             "--help" | "-h" => {
                 eprintln!("Usage: wzp-client [options] [relay-addr]");
                 eprintln!();
@@ -221,6 +235,9 @@ fn parse_args() -> CliArgs {
         room,
         token,
         _metrics_file: metrics_file,
+        version_check,
+        signal,
+        call_target,
     }
 }
 
@@ -239,6 +256,32 @@ async fn main() -> anyhow::Result<()> {
         return Ok(());
     }
 
+    // --version-check: query relay version over QUIC and exit
+    if cli.version_check {
+        let client_config = wzp_transport::client_config();
+        let bind_addr: SocketAddr = "0.0.0.0:0".parse()?;
+        let endpoint = wzp_transport::create_endpoint(bind_addr, None)?;
+        let conn = wzp_transport::connect(&endpoint, cli.relay_addr, "version", client_config).await?;
+        match conn.accept_uni().await {
+            Ok(mut recv) => {
+                let data = recv.read_to_end(256).await.unwrap_or_default();
+                let version = String::from_utf8_lossy(&data);
+                println!("{} {}", cli.relay_addr, version.trim());
+            }
+            Err(e) => {
+                eprintln!("relay {} does not support version query: {e}", cli.relay_addr);
+            }
+        }
+        endpoint.close(0u32.into(), b"done");
+        return Ok(());
+    }
+
+    // --signal mode: persistent signaling for direct calls
+    if cli.signal {
+        let seed = cli.resolve_seed();
+        return run_signal_mode(cli.relay_addr, seed, cli.token, cli.call_target).await;
+    }
+
     let seed = cli.resolve_seed();
 
     info!(
@@ -250,12 +293,11 @@ async fn main() -> anyhow::Result<()> {
         "WarzonePhone client"
     );
 
-    // Hash room name for SNI privacy (or "default" if none specified)
+    // Use raw room name as SNI (consistent with Android + Desktop clients for federation)
     let sni = match &cli.room {
         Some(name) => {
-            let hashed = wzp_crypto::hash_room_name(name);
-            info!(room = %name, hashed = %hashed, "room name hashed for SNI");
-            hashed
+            info!(room = %name, "using room name as SNI");
+            name.clone()
         }
         None => "default".to_string(),
     };
@@ -274,6 +316,26 @@ async fn main() -> anyhow::Result<()> {
 
     let transport = Arc::new(wzp_transport::QuinnTransport::new(connection));
 
+    // Register shutdown handler so SIGTERM/SIGINT always closes QUIC cleanly.
+    // Without this, killed clients leave zombie connections on the relay for ~30s.
+    {
+        let shutdown_transport = transport.clone();
+        tokio::spawn(async move {
+            let mut sigterm = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())
+                .expect("failed to register SIGTERM handler");
+            let mut sigint = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::interrupt())
+                .expect("failed to register SIGINT handler");
+            tokio::select! {
+                _ = sigterm.recv() => { info!("SIGTERM received, closing connection..."); }
+                _ = sigint.recv() => { info!("SIGINT received, closing connection..."); }
+            }
+            // Close the QUIC connection immediately (APPLICATION_CLOSE frame).
+            // Don't call process::exit — let the main task detect the closed
+            // connection and perform clean shutdown (e.g., save recordings).
+            shutdown_transport.connection().close(0u32.into(), b"shutdown");
+        });
+    }
+
     // Send auth token if provided (relay with --auth-url expects this first)
     if let Some(ref token) = cli.token {
         let auth = wzp_proto::SignalMessage::AuthToken {
@@ -624,3 +686,195 @@ async fn run_live(transport: Arc<wzp_transport::QuinnTransport>) -> anyhow::Resu
     info!("done");
     Ok(())
 }
+
+/// Persistent signaling mode for direct 1:1 calls.
+async fn run_signal_mode(
+    relay_addr: SocketAddr,
+    seed: wzp_crypto::Seed,
+    token: Option<String>,
+    call_target: Option<String>,
+) -> anyhow::Result<()> {
+    use wzp_proto::SignalMessage;
+
+    let identity = seed.derive_identity();
+    let pub_id = identity.public_identity();
+    let fp = pub_id.fingerprint.to_string();
+    let identity_pub = *pub_id.signing.as_bytes();
+    info!(fingerprint = %fp, "signal mode");
+
+    // Connect to relay with SNI "_signal"
+    let client_config = wzp_transport::client_config();
+    let bind_addr: SocketAddr = if relay_addr.is_ipv6() {
+        "[::]:0".parse()?
+    } else {
+        "0.0.0.0:0".parse()?
+    };
+    let endpoint = wzp_transport::create_endpoint(bind_addr, None)?;
+    let conn = wzp_transport::connect(&endpoint, relay_addr, "_signal", client_config).await?;
+    let transport = Arc::new(wzp_transport::QuinnTransport::new(conn));
+    info!("connected to relay (signal channel)");
+
+    // Auth if token provided
+    if let Some(ref tok) = token {
+        transport.send_signal(&SignalMessage::AuthToken { token: tok.clone() }).await?;
+    }
+
+    // Register presence (signature not verified in Phase 1)
+    transport.send_signal(&SignalMessage::RegisterPresence {
+        identity_pub,
+        signature: vec![], // Phase 1: not verified
+        alias: None,
+    }).await?;
+
+    // Wait for ack
+    match transport.recv_signal().await? {
+        Some(SignalMessage::RegisterPresenceAck { success: true, .. }) => {
+            info!(fingerprint = %fp, "registered on relay — waiting for calls");
+        }
+        Some(SignalMessage::RegisterPresenceAck { success: false, error }) => {
+            anyhow::bail!("registration failed: {}", error.unwrap_or_default());
+        }
+        other => {
+            anyhow::bail!("unexpected response: {other:?}");
+        }
+    }
+
+    // If --call specified, place the call
+    if let Some(ref target) = call_target {
+        info!(target = %target, "placing direct call...");
+        let call_id = format!("{:016x}", std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos());
+
+        transport.send_signal(&SignalMessage::DirectCallOffer {
+            caller_fingerprint: fp.clone(),
+            caller_alias: None,
+            target_fingerprint: target.clone(),
+            call_id: call_id.clone(),
+            identity_pub,
+            ephemeral_pub: [0u8; 32], // Phase 1: not used for key exchange
+            signature: vec![],
+            supported_profiles: vec![wzp_proto::QualityProfile::GOOD],
+        }).await?;
+    }
+
+    // Signal recv loop — handle incoming signals
+    let signal_transport = transport.clone();
+    let relay = relay_addr;
+    let my_fp = fp.clone();
+    let my_seed = seed.0;
+
+    loop {
+        match signal_transport.recv_signal().await {
+            Ok(Some(msg)) => match msg {
+                SignalMessage::CallRinging { call_id } => {
+                    info!(call_id = %call_id, "ringing...");
+                }
+                SignalMessage::DirectCallOffer { caller_fingerprint, caller_alias, call_id, .. } => {
+                    info!(
+                        from = %caller_fingerprint,
+                        alias = ?caller_alias,
+                        call_id = %call_id,
+                        "incoming call — auto-accepting (generic)"
+                    );
+                    // Auto-accept for CLI testing
+                    let _ = signal_transport.send_signal(&SignalMessage::DirectCallAnswer {
+                        call_id,
+                        accept_mode: wzp_proto::CallAcceptMode::AcceptGeneric,
+                        identity_pub: Some(identity_pub),
+                        ephemeral_pub: None,
+                        signature: None,
+                        chosen_profile: Some(wzp_proto::QualityProfile::GOOD),
+                    }).await;
+                }
+                SignalMessage::DirectCallAnswer { call_id, accept_mode, .. } => {
+                    info!(call_id = %call_id, mode = ?accept_mode, "call answered");
+                }
+                SignalMessage::CallSetup { call_id, room, relay_addr: setup_relay } => {
+                    info!(call_id = %call_id, room = %room, relay = %setup_relay, "call setup — connecting to media room");
+
+                    // Connect to the media room
+                    let media_relay: SocketAddr = setup_relay.parse().unwrap_or(relay);
+                    let media_cfg = wzp_transport::client_config();
+                    match wzp_transport::connect(&endpoint, media_relay, &room, media_cfg).await {
+                        Ok(media_conn) => {
+                            let media_transport = Arc::new(wzp_transport::QuinnTransport::new(media_conn));
+
+                            // Crypto handshake
+                            match wzp_client::handshake::perform_handshake(&*media_transport, &my_seed, None).await {
+                                Ok(_session) => {
+                                    info!("media connected — sending tone (press Ctrl+C to hang up)");
+
+                                    // Simple tone sender for testing
+                                    let mt = media_transport.clone();
+                                    let send_task = tokio::spawn(async move {
+                                        let config = wzp_client::call::CallConfig::default();
+                                        let mut encoder = wzp_client::call::CallEncoder::new(&config);
+                                        let duration = tokio::time::Duration::from_millis(20);
+                                        loop {
+                                            let pcm: Vec<i16> = (0..FRAME_SAMPLES)
+                                                .map(|_| 0i16) // silence — could be tone
+                                                .collect();
+                                            if let Ok(pkts) = encoder.encode_frame(&pcm) {
+                                                for pkt in &pkts {
+                                                    if mt.send_media(pkt).await.is_err() { return; }
+                                                }
+                                            }
+                                            tokio::time::sleep(duration).await;
+                                        }
+                                    });
+
+                                    // Wait for hangup or ctrl+c
+                                    loop {
+                                        tokio::select! {
+                                            sig = signal_transport.recv_signal() => {
+                                                match sig {
+                                                    Ok(Some(SignalMessage::Hangup { .. })) => {
+                                                        info!("remote hung up");
+                                                        break;
+                                                    }
+                                                    Ok(None) | Err(_) => break,
+                                                    _ => {}
+                                                }
+                                            }
+                                            _ = tokio::signal::ctrl_c() => {
+                                                info!("hanging up...");
+                                                let _ = signal_transport.send_signal(&SignalMessage::Hangup {
+                                                    reason: wzp_proto::HangupReason::Normal,
+                                                }).await;
+                                                break;
+                                            }
+                                        }
+                                    }
+
+                                    send_task.abort();
+                                    media_transport.close().await.ok();
+                                    info!("call ended");
+                                }
+                                Err(e) => error!("media handshake failed: {e}"),
+                            }
+                        }
+                        Err(e) => error!("media connect failed: {e}"),
+                    }
+                }
+                SignalMessage::Hangup { reason } => {
+                    info!(reason = ?reason, "call ended by remote");
+                }
+                SignalMessage::Pong { .. } => {}
+                other => {
+                    info!("signal: {:?}", std::mem::discriminant(&other));
+                }
+            },
+            Ok(None) => {
+                info!("signal connection closed");
+                break;
+            }
+            Err(e) => {
+                error!("signal error: {e}");
+                break;
+            }
+        }
+    }
+
+    transport.close().await.ok();
+    Ok(())
+}

crates/wzp-client/src/featherchat.rs

@@ -110,9 +110,15 @@ pub fn signal_to_call_type(signal: &SignalMessage) -> CallSignalType {
         SignalMessage::SessionForward { .. } => CallSignalType::Offer, // reuse
         SignalMessage::SessionForwardAck { .. } => CallSignalType::Offer, // reuse
         SignalMessage::RoomUpdate { .. } => CallSignalType::Offer, // reuse
-        SignalMessage::FederationRoomJoin { .. }
-        | SignalMessage::FederationRoomLeave { .. }
-        | SignalMessage::FederationParticipantUpdate { .. } => CallSignalType::Offer, // relay-only
+        SignalMessage::FederationHello { .. }
+        | SignalMessage::GlobalRoomActive { .. }
+        | SignalMessage::GlobalRoomInactive { .. } => CallSignalType::Offer, // relay-only
+        SignalMessage::DirectCallOffer { .. } => CallSignalType::Offer,
+        SignalMessage::DirectCallAnswer { .. } => CallSignalType::Answer,
+        SignalMessage::CallSetup { .. } => CallSignalType::Offer, // relay-only
+        SignalMessage::CallRinging { .. } => CallSignalType::Ringing,
+        SignalMessage::RegisterPresence { .. }
+        | SignalMessage::RegisterPresenceAck { .. } => CallSignalType::Offer, // relay-only
     }
 }
 

crates/wzp-crypto/src/handshake.rs

@@ -110,7 +110,18 @@ impl KeyExchange for WarzoneKeyExchange {
         hk.expand(b"warzone-session-key", &mut session_key)
             .expect("HKDF expand for session key should not fail");
 
-        Ok(Box::new(ChaChaSession::new(session_key)))
+        // Derive SAS (Short Authentication String) from shared secret only.
+        // The shared secret is identical on both sides (X25519 DH property).
+        // A MITM would produce a different shared secret → different SAS.
+        // We use a dedicated HKDF label so SAS is independent of the session key.
+        let mut sas_key = [0u8; 4];
+        hk.expand(b"warzone-sas-code", &mut sas_key)
+            .expect("HKDF expand for SAS should not fail");
+        let sas_code = u32::from_be_bytes(sas_key) % 10000;
+
+        let mut session = ChaChaSession::new(session_key);
+        session.set_sas(sas_code);
+        Ok(Box::new(session))
     }
 }
 
@@ -211,4 +222,47 @@ mod tests {
 
         assert_eq!(&decrypted, plaintext);
     }
+
+    #[test]
+    fn sas_codes_match_between_peers() {
+        let mut alice = WarzoneKeyExchange::from_identity_seed(&[0xAA; 32]);
+        let mut bob = WarzoneKeyExchange::from_identity_seed(&[0xBB; 32]);
+
+        let alice_eph_pub = alice.generate_ephemeral();
+        let bob_eph_pub = bob.generate_ephemeral();
+
+        let alice_session = alice.derive_session(&bob_eph_pub).unwrap();
+        let bob_session = bob.derive_session(&alice_eph_pub).unwrap();
+
+        let alice_sas = alice_session.sas_code();
+        let bob_sas = bob_session.sas_code();
+
+        assert!(alice_sas.is_some(), "Alice should have SAS");
+        assert!(bob_sas.is_some(), "Bob should have SAS");
+        assert_eq!(alice_sas, bob_sas, "SAS codes must match between peers");
+        assert!(alice_sas.unwrap() < 10000, "SAS should be 4 digits");
+    }
+
+    #[test]
+    fn sas_differs_for_different_peers() {
+        let mut alice = WarzoneKeyExchange::from_identity_seed(&[0xAA; 32]);
+        let mut bob = WarzoneKeyExchange::from_identity_seed(&[0xBB; 32]);
+        let mut eve = WarzoneKeyExchange::from_identity_seed(&[0xEE; 32]);
+
+        let alice_eph = alice.generate_ephemeral();
+        let bob_eph = bob.generate_ephemeral();
+        let eve_eph = eve.generate_ephemeral();
+
+        let alice_bob_session = alice.derive_session(&bob_eph).unwrap();
+
+        // Eve does separate handshake with Bob (MITM scenario)
+        let eve_bob_session = eve.derive_session(&bob_eph).unwrap();
+
+        // SAS codes should differ — Eve's session has different shared secret
+        assert_ne!(
+            alice_bob_session.sas_code(),
+            eve_bob_session.sas_code(),
+            "MITM session should produce different SAS"
+        );
+    }
 }

crates/wzp-crypto/src/session.rs

@@ -26,6 +26,8 @@ pub struct ChaChaSession {
     rekey_mgr: RekeyManager,
     /// Pending ephemeral secret for rekey (stored until peer responds).
     pending_rekey_secret: Option<StaticSecret>,
+    /// Short Authentication String (4-digit code for verbal verification).
+    sas_code: Option<u32>,
 }
 
 impl ChaChaSession {
@@ -46,9 +48,15 @@ impl ChaChaSession {
             recv_seq: 0,
             rekey_mgr: RekeyManager::new(shared_secret),
             pending_rekey_secret: None,
+            sas_code: None,
         }
     }
 
+    /// Set the SAS code (called by key exchange after derivation).
+    pub fn set_sas(&mut self, code: u32) {
+        self.sas_code = Some(code);
+    }
+
     /// Install a new key (after rekeying).
     fn install_key(&mut self, new_key: [u8; 32]) {
         use sha2::Digest;
@@ -136,6 +144,10 @@ impl CryptoSession for ChaChaSession {
 
         Ok(())
     }
+
+    fn sas_code(&self) -> Option<u32> {
+        self.sas_code
+    }
 }
 
 #[cfg(test)]

crates/wzp-fec/src/decoder.rs

@@ -1,6 +1,7 @@
 //! RaptorQ FEC decoder — reassembles source blocks from received source and repair symbols.
 
 use std::collections::HashMap;
+use std::time::Instant;
 
 use raptorq::{EncodingPacket, ObjectTransmissionInformation, PayloadId, SourceBlockDecoder};
 use wzp_proto::error::FecError;
@@ -9,6 +10,9 @@ use wzp_proto::FecDecoder;
 /// Length prefix size (u16 little-endian), must match encoder.
 const LEN_PREFIX: usize = 2;
 
+/// Decoded blocks older than this are eligible for reuse by a new sender.
+const BLOCK_STALE_SECS: u64 = 2;
+
 /// State for one in-flight block being decoded.
 struct BlockState {
     /// Number of source symbols expected.
@@ -21,6 +25,8 @@ struct BlockState {
     decoded: bool,
     /// Cached decoded result.
     result: Option<Vec<Vec<u8>>>,
+    /// When this block was last decoded (for staleness check).
+    decoded_at: Option<Instant>,
 }
 
 /// RaptorQ-based FEC decoder that handles multiple concurrent blocks.
@@ -58,6 +64,7 @@ impl RaptorQFecDecoder {
             symbol_size: self.symbol_size,
             decoded: false,
             result: None,
+            decoded_at: None,
         })
     }
 }
@@ -74,9 +81,21 @@ impl FecDecoder for RaptorQFecDecoder {
         let block = self.get_or_create_block(block_id);
 
         if block.decoded {
-            // Already decoded, ignore additional symbols.
+            // If the block was decoded recently, skip (normal duplicate).
+            // If it's stale (>2s), a new sender is reusing this block_id — reset it.
+            if let Some(at) = block.decoded_at {
+                if at.elapsed().as_secs() >= BLOCK_STALE_SECS {
+                    block.decoded = false;
+                    block.result = None;
+                    block.decoded_at = None;
+                    block.packets.clear();
+                } else {
                     return Ok(());
                 }
+            } else {
+                return Ok(());
+            }
+        }
 
         // Data should already be at symbol_size (length-prefixed and padded by the encoder).
         // But if caller sends raw data, pad it.
@@ -132,6 +151,7 @@ impl FecDecoder for RaptorQFecDecoder {
 
                 let block = self.blocks.get_mut(&block_id).unwrap();
                 block.decoded = true;
+                block.decoded_at = Some(Instant::now());
                 block.result = Some(frames.clone());
                 Ok(Some(frames))
             }

crates/wzp-proto/src/jitter.rs

@@ -273,11 +273,22 @@ impl JitterBuffer {
             return;
         }
 
-        // Check if packet is too old (already played out)
+        // Check if packet is too old (already played out).
+        // A backward jump of >100 seq (~2s at 50fps) indicates a new sender in a
+        // federation room — reset instead of dropping.
         if self.stats.packets_played > 0 && seq_before(seq, self.next_playout_seq) {
+            let backward_distance = self.next_playout_seq.wrapping_sub(seq);
+            tracing::warn!(seq, next = self.next_playout_seq, backward_distance, "jitter: backward seq detected");
+            if backward_distance > 100 {
+                tracing::info!(seq, next = self.next_playout_seq, "jitter: RESET — new sender detected");
+                self.buffer.clear();
+                self.next_playout_seq = seq;
+                self.stats.packets_late = 0;
+            } else {
                 self.stats.packets_late += 1;
                 return;
             }
+        }
 
         // If we haven't started playout yet, adjust next_playout_seq to earliest known
         if self.stats.packets_played == 0 && seq_before(seq, self.next_playout_seq) {
@@ -412,11 +423,22 @@ impl JitterBuffer {
             return;
         }
 
-        // Check if packet is too old (already played out)
+        // Check if packet is too old (already played out).
+        // A backward jump of >100 seq (~2s at 50fps) indicates a new sender in a
+        // federation room — reset instead of dropping.
         if self.stats.packets_played > 0 && seq_before(seq, self.next_playout_seq) {
+            let backward_distance = self.next_playout_seq.wrapping_sub(seq);
+            tracing::warn!(seq, next = self.next_playout_seq, backward_distance, "jitter: backward seq detected");
+            if backward_distance > 100 {
+                tracing::info!(seq, next = self.next_playout_seq, "jitter: RESET — new sender detected");
+                self.buffer.clear();
+                self.next_playout_seq = seq;
+                self.stats.packets_late = 0;
+            } else {
                 self.stats.packets_late += 1;
                 return;
             }
+        }
 
         // If we haven't started playout yet, adjust next_playout_seq to earliest known
         if self.stats.packets_played == 0 && seq_before(seq, self.next_playout_seq) {

crates/wzp-proto/src/lib.rs

@@ -25,8 +25,9 @@ pub mod traits;
 pub use codec_id::{CodecId, QualityProfile};
 pub use error::*;
 pub use packet::{
-    HangupReason, MediaHeader, MediaPacket, MiniFrameContext, MiniHeader, QualityReport,
-    RoomParticipant, SignalMessage, TrunkEntry, TrunkFrame, FRAME_TYPE_FULL, FRAME_TYPE_MINI,
+    CallAcceptMode, HangupReason, MediaHeader, MediaPacket, MiniFrameContext, MiniHeader,
+    QualityReport, RoomParticipant, SignalMessage, TrunkEntry, TrunkFrame, FRAME_TYPE_FULL,
+    FRAME_TYPE_MINI,
 };
 pub use bandwidth::{BandwidthEstimator, CongestionState};
 pub use quality::{AdaptiveQualityController, NetworkContext, Tier};

crates/wzp-proto/src/packet.rs

@@ -659,22 +659,109 @@ pub enum SignalMessage {
 
     // ── Federation signals (relay-to-relay) ──
 
-    /// Federation: a room exists on the sending relay with active local participants.
-    FederationRoomJoin {
+    /// Federation: initial handshake — the connecting relay identifies itself.
+    FederationHello {
+        /// TLS certificate fingerprint of the connecting relay.
+        tls_fingerprint: String,
+    },
+
+    /// Federation: this relay now has local participants in a global room.
+    GlobalRoomActive {
         room: String,
+        /// Participants on the announcing relay (for federated presence).
+        #[serde(default)]
         participants: Vec<RoomParticipant>,
     },
 
-    /// Federation: a room is now empty on the sending relay.
-    FederationRoomLeave {
+    /// Federation: this relay's last local participant left a global room.
+    GlobalRoomInactive {
         room: String,
     },
 
-    /// Federation: local participant list changed for a federated room.
-    FederationParticipantUpdate {
-        room: String,
-        participants: Vec<RoomParticipant>,
+    // ── Direct calling signals (client ↔ relay signaling) ──
+
+    /// Register on relay for direct calls. Sent on `_signal` connections
+    /// after optional AuthToken.
+    RegisterPresence {
+        /// Client's Ed25519 identity public key.
+        identity_pub: [u8; 32],
+        /// Signature over ("register-presence" || identity_pub).
+        signature: Vec<u8>,
+        /// Optional display name.
+        alias: Option<String>,
     },
+
+    /// Relay confirms presence registration.
+    RegisterPresenceAck {
+        success: bool,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        error: Option<String>,
+    },
+
+    /// Direct call offer routed through the relay to a specific peer.
+    DirectCallOffer {
+        /// Caller's fingerprint.
+        caller_fingerprint: String,
+        /// Caller's display name.
+        caller_alias: Option<String>,
+        /// Target's fingerprint.
+        target_fingerprint: String,
+        /// Unique call session ID (UUID).
+        call_id: String,
+        /// Caller's Ed25519 identity pub.
+        identity_pub: [u8; 32],
+        /// Caller's ephemeral X25519 pub (for key exchange on media connect).
+        ephemeral_pub: [u8; 32],
+        /// Signature over (ephemeral_pub || target_fingerprint || call_id).
+        signature: Vec<u8>,
+        /// Supported quality profiles.
+        supported_profiles: Vec<crate::QualityProfile>,
+    },
+
+    /// Callee's response to a direct call.
+    DirectCallAnswer {
+        call_id: String,
+        /// How the callee accepts (or rejects).
+        accept_mode: CallAcceptMode,
+        /// Callee's identity pub (present when accepting).
+        #[serde(skip_serializing_if = "Option::is_none")]
+        identity_pub: Option<[u8; 32]>,
+        /// Callee's ephemeral pub (present when accepting).
+        #[serde(skip_serializing_if = "Option::is_none")]
+        ephemeral_pub: Option<[u8; 32]>,
+        /// Signature (present when accepting).
+        #[serde(skip_serializing_if = "Option::is_none")]
+        signature: Option<Vec<u8>>,
+        /// Chosen quality profile (present when accepting).
+        #[serde(skip_serializing_if = "Option::is_none")]
+        chosen_profile: Option<crate::QualityProfile>,
+    },
+
+    /// Relay tells both parties: media room is ready.
+    CallSetup {
+        call_id: String,
+        /// Room name on the relay for the media session (e.g., "_call:a1b2c3d4").
+        room: String,
+        /// Relay address for the QUIC media connection.
+        relay_addr: String,
+    },
+
+    /// Ringing notification (relay → caller, callee received the offer).
+    CallRinging {
+        call_id: String,
+    },
+}
+
+/// How the callee responds to a direct call.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub enum CallAcceptMode {
+    /// Reject the call.
+    Reject,
+    /// Accept with trust — in Phase 2, this enables P2P (reveals IP).
+    /// In Phase 1, behaves the same as AcceptGeneric.
+    AcceptTrusted,
+    /// Accept with privacy — relay always mediates media.
+    AcceptGeneric,
 }
 
 /// A participant entry in a RoomUpdate message.
@@ -684,6 +771,10 @@ pub struct RoomParticipant {
     pub fingerprint: String,
     /// Optional display name set by the client.
     pub alias: Option<String>,
+    /// Relay label — identifies which relay this participant is connected to.
+    /// None for local participants, Some("Relay B") for federated.
+    #[serde(default)]
+    pub relay_label: Option<String>,
 }
 
 /// Reasons for ending a call.

crates/wzp-proto/src/traits.rs

@@ -132,6 +132,14 @@ pub trait CryptoSession: Send + Sync {
     fn overhead(&self) -> usize {
         16 // ChaCha20-Poly1305 tag
     }
+
+    /// Short Authentication String (SAS) — 4-digit code for verbal verification.
+    /// Both peers derive the same code from the shared secret + identity keys.
+    /// If a MITM relay is intercepting, the codes will differ.
+    /// Returns None if SAS was not computed (e.g., relay-side sessions).
+    fn sas_code(&self) -> Option<u32> {
+        None
+    }
 }
 
 /// Key exchange using the Warzone identity model.

crates/wzp-relay/Cargo.toml

@@ -30,6 +30,7 @@ tower-http = { version = "0.6", features = ["fs"] }
 futures-util = "0.3"
 dirs = "6"
 sha2 = { workspace = true }
+chrono = "0.4"
 
 [[bin]]
 name = "wzp-relay"

crates/wzp-relay/build.rs

@@ -0,0 +1,18 @@
+use std::process::Command;
+
+fn main() {
+    // Get git hash at build time
+    let output = Command::new("git")
+        .args(["rev-parse", "--short", "HEAD"])
+        .output();
+
+    let hash = match output {
+        Ok(o) if o.status.success() => {
+            String::from_utf8_lossy(&o.stdout).trim().to_string()
+        }
+        _ => "unknown".to_string(),
+    };
+
+    println!("cargo:rustc-env=WZP_BUILD_HASH={hash}");
+    println!("cargo:rerun-if-changed=.git/HEAD");
+}

crates/wzp-relay/src/call_registry.rs

@@ -0,0 +1,199 @@
+//! Direct call state tracking.
+//!
+//! Manages the lifecycle of 1:1 direct calls placed via the `_signal` channel.
+//! Each call goes through: Pending → Ringing → Active → Ended.
+
+use std::collections::HashMap;
+use std::time::{Duration, Instant};
+
+/// State of a direct call.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum DirectCallState {
+    /// Offer sent to callee, waiting for response.
+    Pending,
+    /// Callee acknowledged, ringing.
+    Ringing,
+    /// Call accepted, media room active.
+    Active,
+    /// Call ended (hangup, reject, timeout, or error).
+    Ended,
+}
+
+/// A tracked direct call between two users.
+pub struct DirectCall {
+    pub call_id: String,
+    pub caller_fingerprint: String,
+    pub callee_fingerprint: String,
+    pub state: DirectCallState,
+    pub accept_mode: Option<wzp_proto::CallAcceptMode>,
+    /// Private room name (set when accepted).
+    pub room_name: Option<String>,
+    pub created_at: Instant,
+    pub answered_at: Option<Instant>,
+    pub ended_at: Option<Instant>,
+}
+
+/// Registry of active direct calls.
+pub struct CallRegistry {
+    calls: HashMap<String, DirectCall>,
+}
+
+impl CallRegistry {
+    pub fn new() -> Self {
+        Self {
+            calls: HashMap::new(),
+        }
+    }
+
+    /// Create a new pending call. Returns the call_id.
+    pub fn create_call(&mut self, call_id: String, caller_fp: String, callee_fp: String) -> &DirectCall {
+        let call = DirectCall {
+            call_id: call_id.clone(),
+            caller_fingerprint: caller_fp,
+            callee_fingerprint: callee_fp,
+            state: DirectCallState::Pending,
+            accept_mode: None,
+            room_name: None,
+            created_at: Instant::now(),
+            answered_at: None,
+            ended_at: None,
+        };
+        self.calls.insert(call_id.clone(), call);
+        self.calls.get(&call_id).unwrap()
+    }
+
+    /// Get a call by ID.
+    pub fn get(&self, call_id: &str) -> Option<&DirectCall> {
+        self.calls.get(call_id)
+    }
+
+    /// Get a mutable call by ID.
+    pub fn get_mut(&mut self, call_id: &str) -> Option<&mut DirectCall> {
+        self.calls.get_mut(call_id)
+    }
+
+    /// Transition to Ringing state.
+    pub fn set_ringing(&mut self, call_id: &str) -> bool {
+        if let Some(call) = self.calls.get_mut(call_id) {
+            if call.state == DirectCallState::Pending {
+                call.state = DirectCallState::Ringing;
+                return true;
+            }
+        }
+        false
+    }
+
+    /// Transition to Active state.
+    pub fn set_active(&mut self, call_id: &str, mode: wzp_proto::CallAcceptMode, room: String) -> bool {
+        if let Some(call) = self.calls.get_mut(call_id) {
+            if call.state == DirectCallState::Pending || call.state == DirectCallState::Ringing {
+                call.state = DirectCallState::Active;
+                call.accept_mode = Some(mode);
+                call.room_name = Some(room);
+                call.answered_at = Some(Instant::now());
+                return true;
+            }
+        }
+        false
+    }
+
+    /// End a call.
+    pub fn end_call(&mut self, call_id: &str) -> Option<DirectCall> {
+        if let Some(call) = self.calls.get_mut(call_id) {
+            call.state = DirectCallState::Ended;
+            call.ended_at = Some(Instant::now());
+        }
+        self.calls.remove(call_id)
+    }
+
+    /// Find active/pending calls involving a fingerprint.
+    pub fn calls_for_fingerprint(&self, fp: &str) -> Vec<&DirectCall> {
+        self.calls.values()
+            .filter(|c| {
+                c.state != DirectCallState::Ended
+                    && (c.caller_fingerprint == fp || c.callee_fingerprint == fp)
+            })
+            .collect()
+    }
+
+    /// Find the peer's fingerprint in a call.
+    pub fn peer_fingerprint(&self, call_id: &str, my_fp: &str) -> Option<&str> {
+        self.calls.get(call_id).map(|c| {
+            if c.caller_fingerprint == my_fp {
+                c.callee_fingerprint.as_str()
+            } else {
+                c.caller_fingerprint.as_str()
+            }
+        })
+    }
+
+    /// Remove calls that have been pending longer than the timeout.
+    /// Returns call IDs of expired calls.
+    pub fn expire_stale(&mut self, timeout: Duration) -> Vec<DirectCall> {
+        let now = Instant::now();
+        let expired: Vec<String> = self.calls.iter()
+            .filter(|(_, c)| {
+                c.state == DirectCallState::Pending
+                    && now.duration_since(c.created_at) > timeout
+            })
+            .map(|(id, _)| id.clone())
+            .collect();
+
+        expired.into_iter()
+            .filter_map(|id| self.calls.remove(&id))
+            .collect()
+    }
+
+    /// Number of active (non-ended) calls.
+    pub fn active_count(&self) -> usize {
+        self.calls.values()
+            .filter(|c| c.state != DirectCallState::Ended)
+            .count()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn call_lifecycle() {
+        let mut reg = CallRegistry::new();
+        reg.create_call("c1".into(), "alice".into(), "bob".into());
+
+        assert_eq!(reg.get("c1").unwrap().state, DirectCallState::Pending);
+        assert!(reg.set_ringing("c1"));
+        assert_eq!(reg.get("c1").unwrap().state, DirectCallState::Ringing);
+
+        assert!(reg.set_active("c1", wzp_proto::CallAcceptMode::AcceptGeneric, "_call:c1".into()));
+        assert_eq!(reg.get("c1").unwrap().state, DirectCallState::Active);
+        assert_eq!(reg.get("c1").unwrap().room_name.as_deref(), Some("_call:c1"));
+
+        let ended = reg.end_call("c1").unwrap();
+        assert_eq!(ended.state, DirectCallState::Ended);
+        assert_eq!(reg.active_count(), 0);
+    }
+
+    #[test]
+    fn expire_stale_calls() {
+        let mut reg = CallRegistry::new();
+        reg.create_call("c1".into(), "alice".into(), "bob".into());
+
+        // Not expired yet
+        let expired = reg.expire_stale(Duration::from_secs(30));
+        assert!(expired.is_empty());
+
+        // Force expiry with 0 timeout
+        let expired = reg.expire_stale(Duration::from_secs(0));
+        assert_eq!(expired.len(), 1);
+        assert_eq!(expired[0].call_id, "c1");
+    }
+
+    #[test]
+    fn peer_lookup() {
+        let mut reg = CallRegistry::new();
+        reg.create_call("c1".into(), "alice".into(), "bob".into());
+        assert_eq!(reg.peer_fingerprint("c1", "alice"), Some("bob"));
+        assert_eq!(reg.peer_fingerprint("c1", "bob"), Some("alice"));
+    }
+}

crates/wzp-relay/src/config.rs

@@ -15,6 +15,23 @@ pub struct PeerConfig {
     pub label: Option<String>,
 }
 
+/// A trusted relay — accepts inbound federation without needing the peer's address.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct TrustedConfig {
+    /// Expected TLS certificate fingerprint (hex, with colons).
+    pub fingerprint: String,
+    /// Optional human-readable label.
+    #[serde(default)]
+    pub label: Option<String>,
+}
+
+/// A room declared global — bridged across all federated peers.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct GlobalRoomConfig {
+    /// Room name to bridge (e.g., "android").
+    pub name: String,
+}
+
 /// Configuration for the relay daemon.
 ///
 /// All fields have defaults, so a minimal TOML file only needs the
@@ -63,6 +80,19 @@ pub struct RelayConfig {
     /// Federation peer relays.
     #[serde(default)]
     pub peers: Vec<PeerConfig>,
+    /// Global rooms bridged across federation.
+    #[serde(default)]
+    pub global_rooms: Vec<GlobalRoomConfig>,
+    /// Trusted relay fingerprints — accept inbound federation from these relays.
+    /// Unlike [[peers]], no url is needed — the peer connects to us.
+    #[serde(default)]
+    pub trusted: Vec<TrustedConfig>,
+    /// Debug tap: log packet headers for matching rooms ("*" = all rooms).
+    /// Activated via --debug-tap <room> or debug_tap = "room" in TOML.
+    pub debug_tap: Option<String>,
+    /// JSONL event log path for protocol analysis (--event-log).
+    #[serde(skip)]
+    pub event_log: Option<String>,
 }
 
 impl Default for RelayConfig {
@@ -82,6 +112,10 @@ impl Default for RelayConfig {
             ws_port: None,
             static_dir: None,
             peers: Vec::new(),
+            global_rooms: Vec::new(),
+            trusted: Vec::new(),
+            debug_tap: None,
+            event_log: None,
         }
     }
 }
@@ -92,3 +126,85 @@ pub fn load_config(path: &str) -> Result<RelayConfig, anyhow::Error> {
     let config: RelayConfig = toml::from_str(&content)?;
     Ok(config)
 }
+
+/// Info about this relay instance, used to generate personalized example configs.
+pub struct RelayInfo {
+    pub listen_addr: String,
+    pub tls_fingerprint: String,
+    pub public_ip: Option<String>,
+}
+
+/// Load config from path, or create a personalized example config if it doesn't exist.
+pub fn load_or_create_config(path: &str, info: Option<&RelayInfo>) -> Result<RelayConfig, anyhow::Error> {
+    let p = std::path::Path::new(path);
+    if p.exists() {
+        return load_config(path);
+    }
+    // Create parent directory if needed
+    if let Some(parent) = p.parent() {
+        std::fs::create_dir_all(parent)?;
+    }
+    // Generate personalized example config
+    let example = generate_example_config(info);
+    std::fs::write(p, &example)?;
+    eprintln!("Created example config at {path} — edit it and restart.");
+    let config: RelayConfig = toml::from_str(&example)?;
+    Ok(config)
+}
+
+/// Generate an example TOML config, personalized with this relay's info if available.
+fn generate_example_config(info: Option<&RelayInfo>) -> String {
+    let listen = info.map(|i| i.listen_addr.as_str()).unwrap_or("0.0.0.0:4433");
+    let peer_example = if let Some(i) = info {
+        let ip = i.public_ip.as_deref().unwrap_or("this-relay-ip");
+        format!(
+            r#"# Other relays can peer with this relay using:
+# [[peers]]
+# url = "{ip}:{port}"
+# fingerprint = "{fp}"
+# label = "This Relay""#,
+            port = listen.rsplit(':').next().unwrap_or("4433"),
+            fp = i.tls_fingerprint,
+        )
+    } else {
+        "# To peer with another relay, add its url + fingerprint:".to_string()
+    };
+
+    format!(
+        r#"# WarzonePhone Relay Configuration
+# See docs/ADMINISTRATION.md for full reference.
+
+# Listen address for client connections
+listen_addr = "{listen}"
+
+# Maximum concurrent sessions
+# max_sessions = 100
+
+# Prometheus metrics endpoint (uncomment to enable)
+# metrics_port = 9090
+
+# featherChat auth endpoint (uncomment to enable)
+# auth_url = "https://chat.example.com/v1/auth/validate"
+
+{peer_example}
+
+# Federation: peer relays we connect to (outbound)
+# [[peers]]
+# url = "other-relay.example.com:4433"
+# fingerprint = "aa:bb:cc:dd:..."
+# label = "Relay B"
+
+# Federation: relays we trust inbound connections from
+# [[trusted]]
+# fingerprint = "ee:ff:00:11:..."
+# label = "Relay X"
+
+# Global rooms bridged across all federated peers
+# [[global_rooms]]
+# name = "general"
+
+# Debug: log packet headers for a room ("*" for all)
+# debug_tap = "*"
+"#
+    )
+}

crates/wzp-relay/src/event_log.rs

@@ -0,0 +1,201 @@
+//! JSONL event log for protocol analysis.
+//!
+//! When `--event-log <path>` is set, every media packet emits a structured
+//! event at each decision point (recv, forward, drop, deliver).
+//! Use `wzp-analyzer` to correlate events across multiple relays.
+
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use serde::Serialize;
+use tokio::sync::mpsc;
+use tracing::{error, info};
+
+/// A single protocol event for JSONL output.
+#[derive(Debug, Serialize)]
+pub struct Event {
+    /// ISO 8601 timestamp with microseconds.
+    pub ts: String,
+    /// Event type.
+    pub event: &'static str,
+    /// Room name.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub room: Option<String>,
+    /// Source address or peer label.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub src: Option<String>,
+    /// Packet sequence number.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub seq: Option<u16>,
+    /// Codec identifier.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub codec: Option<String>,
+    /// FEC block ID.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub fec_block: Option<u8>,
+    /// FEC symbol index.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub fec_sym: Option<u8>,
+    /// Is FEC repair packet.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub repair: Option<bool>,
+    /// Payload length in bytes.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub len: Option<usize>,
+    /// Number of recipients.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub to_count: Option<usize>,
+    /// Peer label (for federation events).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub peer: Option<String>,
+    /// Drop/error reason.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub reason: Option<String>,
+    /// Presence action (active/inactive).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub action: Option<String>,
+    /// Participant count (presence events).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub participants: Option<usize>,
+}
+
+impl Event {
+    fn now() -> String {
+        chrono::Utc::now().format("%Y-%m-%dT%H:%M:%S%.6fZ").to_string()
+    }
+
+    /// Create a minimal event with just type and timestamp.
+    pub fn new(event: &'static str) -> Self {
+        Self {
+            ts: Self::now(),
+            event,
+            room: None,
+            src: None,
+            seq: None,
+            codec: None,
+            fec_block: None,
+            fec_sym: None,
+            repair: None,
+            len: None,
+            to_count: None,
+            peer: None,
+            reason: None,
+            action: None,
+            participants: None,
+        }
+    }
+
+    /// Set room.
+    pub fn room(mut self, room: &str) -> Self { self.room = Some(room.to_string()); self }
+    /// Set source.
+    pub fn src(mut self, src: &str) -> Self { self.src = Some(src.to_string()); self }
+    /// Set packet header fields from a MediaPacket.
+    pub fn packet(mut self, pkt: &wzp_proto::MediaPacket) -> Self {
+        self.seq = Some(pkt.header.seq);
+        self.codec = Some(format!("{:?}", pkt.header.codec_id));
+        self.fec_block = Some(pkt.header.fec_block);
+        self.fec_sym = Some(pkt.header.fec_symbol);
+        self.repair = Some(pkt.header.is_repair);
+        self.len = Some(pkt.payload.len());
+        self
+    }
+    /// Set seq only (when full packet not available).
+    pub fn seq(mut self, seq: u16) -> Self { self.seq = Some(seq); self }
+    /// Set payload length.
+    pub fn len(mut self, len: usize) -> Self { self.len = Some(len); self }
+    /// Set recipient count.
+    pub fn to_count(mut self, n: usize) -> Self { self.to_count = Some(n); self }
+    /// Set peer label.
+    pub fn peer(mut self, peer: &str) -> Self { self.peer = Some(peer.to_string()); self }
+    /// Set drop reason.
+    pub fn reason(mut self, reason: &str) -> Self { self.reason = Some(reason.to_string()); self }
+    /// Set presence action.
+    pub fn action(mut self, action: &str) -> Self { self.action = Some(action.to_string()); self }
+    /// Set participant count.
+    pub fn participants(mut self, n: usize) -> Self { self.participants = Some(n); self }
+}
+
+/// Handle for emitting events. Cheap to clone.
+#[derive(Clone)]
+pub struct EventLog {
+    tx: mpsc::UnboundedSender<Event>,
+}
+
+impl EventLog {
+    /// Emit an event (non-blocking, drops if channel is full).
+    pub fn emit(&self, event: Event) {
+        let _ = self.tx.send(event);
+    }
+}
+
+/// No-op event log for when `--event-log` is not set.
+/// All methods are no-ops that compile to nothing.
+#[derive(Clone)]
+pub struct NoopEventLog;
+
+/// Unified event log handle — either real or no-op.
+#[derive(Clone)]
+pub enum EventLogger {
+    Active(EventLog),
+    Noop,
+}
+
+impl EventLogger {
+    pub fn emit(&self, event: Event) {
+        if let EventLogger::Active(log) = self {
+            log.emit(event);
+        }
+    }
+
+    pub fn is_active(&self) -> bool {
+        matches!(self, EventLogger::Active(_))
+    }
+}
+
+/// Start the event log writer. Returns an `EventLogger` handle.
+pub fn start_event_log(path: Option<PathBuf>) -> EventLogger {
+    match path {
+        Some(path) => {
+            let (tx, rx) = mpsc::unbounded_channel();
+            tokio::spawn(writer_task(path, rx));
+            info!("event log enabled");
+            EventLogger::Active(EventLog { tx })
+        }
+        None => EventLogger::Noop,
+    }
+}
+
+/// Background task that writes events to a JSONL file.
+async fn writer_task(path: PathBuf, mut rx: mpsc::UnboundedReceiver<Event>) {
+    use tokio::io::AsyncWriteExt;
+
+    let file = match tokio::fs::File::create(&path).await {
+        Ok(f) => f,
+        Err(e) => {
+            error!("failed to create event log {}: {e}", path.display());
+            return;
+        }
+    };
+    let mut writer = tokio::io::BufWriter::new(file);
+    let mut count: u64 = 0;
+
+    while let Some(event) = rx.recv().await {
+        match serde_json::to_string(&event) {
+            Ok(json) => {
+                if writer.write_all(json.as_bytes()).await.is_err() { break; }
+                if writer.write_all(b"\n").await.is_err() { break; }
+                count += 1;
+                // Flush every 100 events
+                if count % 100 == 0 {
+                    let _ = writer.flush().await;
+                }
+            }
+            Err(e) => {
+                error!("event log serialize error: {e}");
+            }
+        }
+    }
+
+    let _ = writer.flush().await;
+    info!(events = count, "event log closed");
+}

crates/wzp-relay/src/handshake.rs

@@ -78,31 +78,26 @@ pub async fn accept_handshake(
     };
     transport.send_signal(&answer).await?;
 
-    // Derive caller fingerprint from their identity public key (first 8 bytes as hex)
-    let caller_fp = caller_identity_pub[..8]
-        .iter()
-        .map(|b| format!("{b:02x}"))
-        .collect::<String>();
+    // Derive caller fingerprint: SHA-256(Ed25519 pub)[:16], formatted as xxxx:xxxx:...
+    // Must match the format used in signal registration and presence.
+    let caller_fp = {
+        use sha2::{Sha256, Digest};
+        let hash = Sha256::digest(&caller_identity_pub);
+        let fp = wzp_crypto::Fingerprint([
+            hash[0], hash[1], hash[2], hash[3], hash[4], hash[5], hash[6], hash[7],
+            hash[8], hash[9], hash[10], hash[11], hash[12], hash[13], hash[14], hash[15],
+        ]);
+        fp.to_string()
+    };
 
     Ok((session, chosen_profile, caller_fp, caller_alias))
 }
 
 /// Select the best quality profile from those the caller supports.
 fn choose_profile(supported: &[QualityProfile]) -> QualityProfile {
-    // Prefer higher-quality profiles. Use GOOD as default if supported list is empty.
-    if supported.is_empty() {
-        return QualityProfile::GOOD;
-    }
-    // Pick the profile with the highest bitrate.
-    supported
-        .iter()
-        .max_by(|a, b| {
-            a.total_bitrate_kbps()
-                .partial_cmp(&b.total_bitrate_kbps())
-                .unwrap_or(std::cmp::Ordering::Equal)
-        })
-        .copied()
-        .unwrap_or(QualityProfile::GOOD)
+    // Cap at GOOD (24k) for now — studio tiers (32k/48k/64k) not yet tested
+    // for federation reliability (large packets may exceed path MTU).
+    QualityProfile::GOOD
 }
 
 #[cfg(test)]

crates/wzp-relay/src/lib.rs

@@ -8,8 +8,11 @@
 //! quality transitions.
 
 pub mod auth;
+pub mod call_registry;
 pub mod config;
+pub mod event_log;
 pub mod federation;
+pub mod signal_hub;
 pub mod handshake;
 pub mod metrics;
 pub mod pipeline;

crates/wzp-relay/src/main.rs

@@ -15,7 +15,7 @@ use std::time::Duration;
 use tokio::sync::Mutex;
 use tracing::{error, info, warn};
 
-use wzp_proto::MediaTransport;
+use wzp_proto::{MediaTransport, SignalMessage};
 use wzp_relay::config::RelayConfig;
 use wzp_relay::metrics::RelayMetrics;
 use wzp_relay::pipeline::{PipelineConfig, RelayPipeline};
@@ -23,26 +23,44 @@ use wzp_relay::presence::PresenceRegistry;
 use wzp_relay::room::{self, RoomManager};
 use wzp_relay::session_mgr::SessionManager;
 
-fn parse_args() -> RelayConfig {
+/// Parsed CLI result — config + identity path.
+struct CliResult {
+    config: RelayConfig,
+    identity_path: Option<String>,
+    config_file: Option<String>,
+    config_needs_create: bool,
+}
+
+fn parse_args() -> CliResult {
     let args: Vec<String> = std::env::args().collect();
 
-    // Check for --config first to use as base
+    // First pass: extract --config and --identity
     let mut config_file = None;
+    let mut identity_path = None;
     let mut i = 1;
     while i < args.len() {
-        if args[i] == "--config" {
-            i += 1;
-            config_file = args.get(i).cloned();
+        match args[i].as_str() {
+            "--config" | "-c" => { i += 1; config_file = args.get(i).cloned(); }
+            "--identity" | "-i" => { i += 1; identity_path = args.get(i).cloned(); }
+            _ => {}
         }
         i += 1;
     }
 
+    // Track if we need to create the config after identity is known
+    let config_needs_create = config_file.as_ref().map(|p| !std::path::Path::new(p).exists()).unwrap_or(false);
+
     let mut config = if let Some(ref path) = config_file {
+        if config_needs_create {
+            // Will be re-created with personalized info after identity is loaded
+            RelayConfig::default()
+        } else {
             wzp_relay::config::load_config(path)
                 .unwrap_or_else(|e| {
                     eprintln!("failed to load config from {path}: {e}");
                     std::process::exit(1);
                 })
+        }
     } else {
         RelayConfig::default()
     };
@@ -51,7 +69,8 @@ fn parse_args() -> RelayConfig {
     let mut i = 1;
     while i < args.len() {
         match args[i].as_str() {
-            "--config" => { i += 1; } // already handled
+            "--config" | "-c" => { i += 1; } // already handled
+            "--identity" | "-i" => { i += 1; } // already handled
             "--listen" => {
                 i += 1;
                 config.listen_addr = args.get(i).expect("--listen requires an address")
@@ -104,6 +123,28 @@ fn parse_args() -> RelayConfig {
                     args.get(i).expect("--static-dir requires a directory path").to_string(),
                 );
             }
+            "--global-room" => {
+                i += 1;
+                config.global_rooms.push(wzp_relay::config::GlobalRoomConfig {
+                    name: args.get(i).expect("--global-room requires a room name").to_string(),
+                });
+            }
+            "--debug-tap" => {
+                i += 1;
+                config.debug_tap = Some(
+                    args.get(i).expect("--debug-tap requires a room name (or '*' for all)").to_string(),
+                );
+            }
+            "--event-log" => {
+                i += 1;
+                config.event_log = Some(
+                    args.get(i).expect("--event-log requires a file path").to_string(),
+                );
+            }
+            "--version" | "-V" => {
+                println!("wzp-relay {}", env!("WZP_BUILD_HASH"));
+                std::process::exit(0);
+            }
             "--mesh-status" => {
                 // Print mesh table from a fresh registry and exit.
                 // In practice this is useful after the relay has been running;
@@ -116,7 +157,8 @@ fn parse_args() -> RelayConfig {
                 eprintln!("Usage: wzp-relay [--config <path>] [--listen <addr>] [--remote <addr>] [--auth-url <url>] [--metrics-port <port>] [--probe <addr>]... [--probe-mesh] [--mesh-status]");
                 eprintln!();
                 eprintln!("Options:");
-                eprintln!("  --config <path>        Load configuration from TOML file (peers, listen, etc.)");
+                eprintln!("  -c, --config <path>    Load config from TOML file (creates example if missing)");
+                eprintln!("  -i, --identity <path>  Identity file path (creates if missing, uses OsRng)");
                 eprintln!("  --listen <addr>        Listen address (default: 0.0.0.0:4433)");
                 eprintln!("  --remote <addr>        Remote relay for forwarding (disables room mode)");
                 eprintln!("  --auth-url <url>       featherChat auth endpoint (e.g., https://chat.example.com/v1/auth/validate)");
@@ -126,6 +168,8 @@ fn parse_args() -> RelayConfig {
                 eprintln!("  --probe-mesh           Enable mesh mode (mark config flag, probes all --probe targets).");
                 eprintln!("  --mesh-status          Print mesh health table and exit (diagnostic).");
                 eprintln!("  --trunking             Enable trunk batching for outgoing media in room mode.");
+                eprintln!("  --global-room <name>   Declare a room as global (bridged across federation). Repeatable.");
+                eprintln!("  --debug-tap <room>     Log packet headers for a room ('*' for all rooms).");
                 eprintln!("  --ws-port <port>       WebSocket listener port for browser clients (e.g., 8080).");
                 eprintln!("  --static-dir <dir>     Directory to serve static files from (HTML/JS/WASM).");
                 eprintln!();
@@ -140,7 +184,7 @@ fn parse_args() -> RelayConfig {
         }
         i += 1;
     }
-    config
+    CliResult { config, identity_path, config_file, config_needs_create }
 }
 
 struct RelayStats {
@@ -223,10 +267,14 @@ fn detect_public_ip() -> Option<String> {
     None
 }
 
+/// Build-time git hash, set by build.rs or env.
+const BUILD_GIT_HASH: &str = env!("WZP_BUILD_HASH");
+
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
-    let config = parse_args();
+    let CliResult { mut config, identity_path, config_file, config_needs_create } = parse_args();
     tracing_subscriber::fmt().init();
+    info!(version = BUILD_GIT_HASH, "wzp-relay build");
     rustls::crypto::ring::default_provider()
         .install_default()
         .expect("failed to install rustls crypto provider");
@@ -246,36 +294,41 @@ async fn main() -> anyhow::Result<()> {
         tokio::spawn(wzp_relay::metrics::serve_metrics(port, m, p, rr));
     }
 
-    // Load or generate relay identity — persisted in ~/.wzp/relay-identity
+    // Load or generate relay identity
     let relay_seed = {
-        let config_dir = dirs::home_dir()
+        let id_path = match identity_path {
+            Some(ref p) => std::path::PathBuf::from(p),
+            None => dirs::home_dir()
                 .unwrap_or_else(|| std::path::PathBuf::from("."))
-            .join(".wzp");
-        let identity_path = config_dir.join("relay-identity");
-        if identity_path.exists() {
-            if let Ok(hex) = std::fs::read_to_string(&identity_path) {
+                .join(".wzp")
+                .join("relay-identity"),
+        };
+        if id_path.exists() {
+            if let Ok(hex) = std::fs::read_to_string(&id_path) {
                 if let Ok(s) = wzp_crypto::Seed::from_hex(hex.trim()) {
-                    info!("loaded relay identity from {}", identity_path.display());
+                    info!("loaded relay identity from {}", id_path.display());
                     s
                 } else {
-                    warn!("corrupt relay identity file, generating new");
+                    warn!("corrupt identity file {}, generating new", id_path.display());
                     let s = wzp_crypto::Seed::generate();
                     let hex: String = s.0.iter().map(|b| format!("{b:02x}")).collect();
-                    let _ = std::fs::write(&identity_path, &hex);
+                    let _ = std::fs::write(&id_path, &hex);
                     s
                 }
             } else {
                 let s = wzp_crypto::Seed::generate();
                 let hex: String = s.0.iter().map(|b| format!("{b:02x}")).collect();
-                let _ = std::fs::write(&identity_path, &hex);
+                let _ = std::fs::write(&id_path, &hex);
                 s
             }
         } else {
             let s = wzp_crypto::Seed::generate();
-            let _ = std::fs::create_dir_all(&config_dir);
+            if let Some(parent) = id_path.parent() {
+                let _ = std::fs::create_dir_all(parent);
+            }
             let hex: String = s.0.iter().map(|b| format!("{b:02x}")).collect();
-            let _ = std::fs::write(&identity_path, &hex);
-            info!("generated relay identity at {}", identity_path.display());
+            let _ = std::fs::write(&id_path, &hex);
+            info!("generated relay identity at {}", id_path.display());
             s
         }
     };
@@ -286,9 +339,23 @@ async fn main() -> anyhow::Result<()> {
     let tls_fp = wzp_transport::tls_fingerprint(&cert_der);
     info!(tls_fingerprint = %tls_fp, "TLS certificate (deterministic from relay identity)");
 
+    // Create personalized config file if it was missing
+    let public_ip = detect_public_ip();
+    if config_needs_create {
+        if let Some(ref path) = config_file {
+            let info = wzp_relay::config::RelayInfo {
+                listen_addr: config.listen_addr.to_string(),
+                tls_fingerprint: tls_fp.clone(),
+                public_ip: public_ip.clone(),
+            };
+            if let Err(e) = wzp_relay::config::load_or_create_config(path, Some(&info)) {
+                warn!("failed to create config: {e}");
+            }
+        }
+    }
+
     // Print federation hint with our public IP + listen port + TLS fingerprint
     let listen_port = config.listen_addr.port();
-    let public_ip = detect_public_ip();
     if let Some(ip) = &public_ip {
         info!("federation: to peer with this relay, add to relay.toml:");
         info!("  [[peers]]");
@@ -296,13 +363,19 @@ async fn main() -> anyhow::Result<()> {
         info!("  fingerprint = \"{tls_fp}\"");
     }
 
-    // Log configured peers
+    // Log configured peers and trusted relays
     if !config.peers.is_empty() {
         info!(count = config.peers.len(), "federation peers configured");
         for p in &config.peers {
             info!(url = %p.url, label = ?p.label, "  peer");
         }
     }
+    if !config.trusted.is_empty() {
+        info!(count = config.trusted.len(), "trusted relays configured");
+        for t in &config.trusted {
+            info!(fingerprint = %t.fingerprint, label = ?t.label, "  trusted");
+        }
+    }
     let endpoint = wzp_transport::create_endpoint(config.listen_addr, Some(server_config))?;
 
     // Forward mode
@@ -320,13 +393,26 @@ async fn main() -> anyhow::Result<()> {
     // Room manager (room mode only)
     let room_mgr = Arc::new(Mutex::new(RoomManager::new()));
 
+    // Event log for protocol analysis
+    let event_log = wzp_relay::event_log::start_event_log(
+        config.event_log.as_ref().map(std::path::PathBuf::from)
+    );
+
     // Federation manager
-    let federation_mgr = if !config.peers.is_empty() {
+    let global_room_set: std::collections::HashSet<String> = config.global_rooms.iter()
+        .map(|g| g.name.clone())
+        .collect();
+
+    let federation_mgr = if !config.peers.is_empty() || !config.trusted.is_empty() || !global_room_set.is_empty() {
         let fm = Arc::new(wzp_relay::federation::FederationManager::new(
             config.peers.clone(),
+            config.trusted.clone(),
+            global_room_set.clone(),
             room_mgr.clone(),
             endpoint.clone(),
             tls_fp.clone(),
+            metrics.clone(),
+            event_log.clone(),
         ));
         let fm_run = fm.clone();
         tokio::spawn(async move { fm_run.run().await });
@@ -338,6 +424,10 @@ async fn main() -> anyhow::Result<()> {
     // Session manager — enforces max concurrent sessions
     let session_mgr = Arc::new(Mutex::new(SessionManager::new(config.max_sessions)));
 
+    // Signal hub + call registry for direct 1:1 calls
+    let signal_hub = Arc::new(Mutex::new(wzp_relay::signal_hub::SignalHub::new()));
+    let call_registry = Arc::new(Mutex::new(wzp_relay::call_registry::CallRegistry::new()));
+
     // Spawn inter-relay health probes via ProbeMesh coordinator
     if !config.probe_targets.is_empty() {
         let mesh = wzp_relay::probe::ProbeMesh::new(
@@ -372,6 +462,15 @@ async fn main() -> anyhow::Result<()> {
     } else {
         info!("auth disabled — any client can connect (use --auth-url to enable)");
     }
+    if !config.global_rooms.is_empty() {
+        info!(count = config.global_rooms.len(), "global rooms configured");
+        for g in &config.global_rooms {
+            info!(name = %g.name, "  global room");
+        }
+    }
+    if let Some(ref tap) = config.debug_tap {
+        info!(filter = %tap, "debug tap enabled — logging packet headers");
+    }
 
     info!("Listening for connections...");
 
@@ -388,9 +487,13 @@ async fn main() -> anyhow::Result<()> {
         let relay_seed_bytes = relay_seed.0;
         let metrics = metrics.clone();
         let trunking_enabled = config.trunking_enabled;
+        let debug_tap = config.debug_tap.as_ref().map(|filter| room::DebugTap { room_filter: filter.clone() });
         let presence = presence.clone();
         let route_resolver = route_resolver.clone();
         let federation_mgr = federation_mgr.clone();
+        let signal_hub = signal_hub.clone();
+        let call_registry = call_registry.clone();
+        let listen_addr_str = config.listen_addr.to_string();
 
         tokio::spawn(async move {
             let addr = connection.remote_address();
@@ -406,12 +509,22 @@ async fn main() -> anyhow::Result<()> {
             let transport = Arc::new(wzp_transport::QuinnTransport::new(connection));
 
             // Ping connections: client just measures QUIC connect RTT.
-            // No handshake, no streams — client closes immediately after connecting.
             if room_name == "ping" {
                 info!(%addr, "ping connection (RTT probe)");
                 return;
             }
 
+            // Version query: respond with build hash over a uni stream.
+            if room_name == "version" {
+                if let Ok(mut send) = transport.connection().open_uni().await {
+                    let _ = send.write_all(BUILD_GIT_HASH.as_bytes()).await;
+                    let _ = send.finish();
+                    // Wait for client to read before closing
+                    tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+                }
+                return;
+            }
+
             // Probe connections use SNI "_probe" to identify themselves.
             // They skip auth + handshake and just do Ping->Pong + presence gossip.
             if room_name == "_probe" {
@@ -501,35 +614,291 @@ async fn main() -> anyhow::Result<()> {
             // Federation connections use SNI "_federation"
             if room_name == "_federation" {
                 if let Some(ref fm) = federation_mgr {
-                    // Check if we recognize this peer by TLS fingerprint
-                    let peer_fp = wzp_transport::tls_fingerprint(
-                        &transport.connection()
-                            .peer_identity()
-                            .and_then(|id| id.downcast::<Vec<rustls::pki_types::CertificateDer>>().ok())
-                            .and_then(|certs| certs.first().cloned())
-                            .map(|c| c.to_vec())
-                            .unwrap_or_default()
-                    );
-                    if let Some(peer_config) = fm.find_peer_by_fingerprint(&peer_fp) {
-                        let peer_config = peer_config.clone();
+                    // Wait for FederationHello to identify the connecting relay
+                    let hello_fp = match tokio::time::timeout(
+                        std::time::Duration::from_secs(5),
+                        transport.recv_signal(),
+                    ).await {
+                        Ok(Ok(Some(wzp_proto::SignalMessage::FederationHello { tls_fingerprint }))) => tls_fingerprint,
+                        _ => {
+                            warn!(%addr, "federation: no hello received, closing");
+                            return;
+                        }
+                    };
+
+                    if let Some(label) = fm.check_inbound_trust(addr, &hello_fp) {
+                        let peer_config = wzp_relay::config::PeerConfig {
+                            url: addr.to_string(),
+                            fingerprint: hello_fp,
+                            label: Some(label.clone()),
+                        };
                         let fm = fm.clone();
-                        info!(%addr, label = ?peer_config.label, "inbound federation connection accepted");
+                        info!(%addr, label = %label, "inbound federation accepted (trusted)");
                         fm.handle_inbound(transport, peer_config).await;
                     } else {
-                        warn!(%addr, "unknown relay wants to federate");
+                        warn!(%addr, fp = %hello_fp, "unknown relay wants to federate");
                         info!("  to accept, add to relay.toml:");
-                        info!("  [[peers]]");
-                        info!("  url = \"{addr}\"");
-                        info!("  fingerprint = \"{peer_fp}\"");
-                        transport.close().await.ok();
+                        info!("  [[trusted]]");
+                        info!("  fingerprint = \"{hello_fp}\"");
+                        info!("  label = \"Relay at {addr}\"");
                     }
                 } else {
-                    info!(%addr, "federation connection rejected (no peers configured)");
-                    transport.close().await.ok();
+                    info!(%addr, "federation connection rejected (no federation configured)");
                 }
                 return;
             }
 
+            // Direct calling: persistent signaling connection
+            if room_name == "_signal" {
+                info!(%addr, "signal connection");
+
+                // Optional auth
+                let auth_fp: Option<String> = if let Some(ref url) = auth_url {
+                    match transport.recv_signal().await {
+                        Ok(Some(SignalMessage::AuthToken { token })) => {
+                            match wzp_relay::auth::validate_token(url, &token).await {
+                                Ok(client) => Some(client.fingerprint),
+                                Err(e) => {
+                                    error!(%addr, "signal auth failed: {e}");
+                                    return;
+                                }
+                            }
+                        }
+                        _ => { warn!(%addr, "signal: expected AuthToken"); return; }
+                    }
+                } else {
+                    None
+                };
+
+                // Wait for RegisterPresence
+                let (client_fp, client_alias) = match tokio::time::timeout(
+                    std::time::Duration::from_secs(10),
+                    transport.recv_signal(),
+                ).await {
+                    Ok(Ok(Some(SignalMessage::RegisterPresence { identity_pub, signature: _, alias }))) => {
+                        // Compute fingerprint: SHA-256(Ed25519 pub key)[:16], same as Fingerprint type
+                        let fp = {
+                            use sha2::{Sha256, Digest};
+                            let hash = Sha256::digest(&identity_pub);
+                            let fingerprint = wzp_crypto::Fingerprint([
+                                hash[0], hash[1], hash[2], hash[3], hash[4], hash[5], hash[6], hash[7],
+                                hash[8], hash[9], hash[10], hash[11], hash[12], hash[13], hash[14], hash[15],
+                            ]);
+                            fingerprint.to_string()
+                        };
+                        let fp = auth_fp.unwrap_or(fp);
+                        (fp, alias)
+                    }
+                    _ => {
+                        warn!(%addr, "signal: no RegisterPresence received");
+                        return;
+                    }
+                };
+
+                // Register in signal hub + presence
+                {
+                    let mut hub = signal_hub.lock().await;
+                    hub.register(client_fp.clone(), transport.clone(), client_alias.clone());
+                }
+                {
+                    let mut reg = presence.lock().await;
+                    reg.register_local(&client_fp, client_alias.clone(), None);
+                }
+
+                // Send ack
+                let _ = transport.send_signal(&SignalMessage::RegisterPresenceAck {
+                    success: true,
+                    error: None,
+                }).await;
+
+                info!(%addr, fingerprint = %client_fp, alias = ?client_alias, "signal client registered");
+
+                // Signal recv loop
+                loop {
+                    match transport.recv_signal().await {
+                        Ok(Some(msg)) => {
+                            match msg {
+                                SignalMessage::DirectCallOffer { ref target_fingerprint, ref call_id, ref caller_alias, .. } => {
+                                    let target_fp = target_fingerprint.clone();
+                                    let call_id = call_id.clone();
+
+                                    // Check if target is online
+                                    let online = {
+                                        let hub = signal_hub.lock().await;
+                                        hub.is_online(&target_fp)
+                                    };
+                                    if !online {
+                                        info!(%addr, target = %target_fp, "call target not online");
+                                        let _ = transport.send_signal(&SignalMessage::Hangup {
+                                            reason: wzp_proto::HangupReason::Normal,
+                                        }).await;
+                                        continue;
+                                    }
+
+                                    // Create call in registry
+                                    {
+                                        let mut reg = call_registry.lock().await;
+                                        reg.create_call(call_id.clone(), client_fp.clone(), target_fp.clone());
+                                    }
+
+                                    // Forward offer to callee
+                                    info!(caller = %client_fp, callee = %target_fp, call_id = %call_id, "routing direct call offer");
+                                    let hub = signal_hub.lock().await;
+                                    if let Err(e) = hub.send_to(&target_fp, &msg).await {
+                                        warn!("failed to forward call offer: {e}");
+                                    }
+
+                                    // Send ringing to caller
+                                    drop(hub);
+                                    let _ = transport.send_signal(&SignalMessage::CallRinging {
+                                        call_id: call_id.clone(),
+                                    }).await;
+                                }
+
+                                SignalMessage::DirectCallAnswer { ref call_id, ref accept_mode, .. } => {
+                                    let call_id = call_id.clone();
+                                    let mode = *accept_mode;
+
+                                    let peer_fp = {
+                                        let reg = call_registry.lock().await;
+                                        reg.peer_fingerprint(&call_id, &client_fp).map(|s| s.to_string())
+                                    };
+
+                                    let Some(peer_fp) = peer_fp else {
+                                        warn!(call_id = %call_id, "answer for unknown call");
+                                        continue;
+                                    };
+
+                                    if mode == wzp_proto::CallAcceptMode::Reject {
+                                        info!(call_id = %call_id, "call rejected");
+                                        let mut reg = call_registry.lock().await;
+                                        reg.end_call(&call_id);
+                                        drop(reg);
+                                        let hub = signal_hub.lock().await;
+                                        let _ = hub.send_to(&peer_fp, &SignalMessage::Hangup {
+                                            reason: wzp_proto::HangupReason::Normal,
+                                        }).await;
+                                    } else {
+                                        // Accept — create private room
+                                        let room = format!("call-{call_id}");
+                                        {
+                                            let mut reg = call_registry.lock().await;
+                                            reg.set_active(&call_id, mode, room.clone());
+                                        }
+                                        info!(call_id = %call_id, room = %room, mode = ?mode, "call accepted, creating room");
+
+                                        // Forward answer to caller
+                                        {
+                                            let hub = signal_hub.lock().await;
+                                            let _ = hub.send_to(&peer_fp, &msg).await;
+                                        }
+
+                                        // Send CallSetup to both parties
+                                        // Use the address the client connected to (their remote addr
+                                        // is our perspective, but we need our listen addr).
+                                        // Replace 0.0.0.0 with the client's destination IP.
+                                        let relay_addr_for_setup = if listen_addr_str.starts_with("0.0.0.0:") {
+                                            let port = &listen_addr_str[8..];
+                                            // Use the local IP from the client's connection
+                                            let local_ip = addr.ip();
+                                            if local_ip.is_loopback() {
+                                                format!("127.0.0.1:{port}")
+                                            } else {
+                                                format!("{local_ip}:{port}")
+                                            }
+                                        } else {
+                                            listen_addr_str.clone()
+                                        };
+                                        let setup = SignalMessage::CallSetup {
+                                            call_id: call_id.clone(),
+                                            room: room.clone(),
+                                            relay_addr: relay_addr_for_setup,
+                                        };
+                                        {
+                                            let hub = signal_hub.lock().await;
+                                            let _ = hub.send_to(&peer_fp, &setup).await;
+                                            let _ = hub.send_to(&client_fp, &setup).await;
+                                        }
+                                    }
+                                }
+
+                                SignalMessage::Hangup { .. } => {
+                                    // Forward hangup to all active calls for this user
+                                    let calls = {
+                                        let reg = call_registry.lock().await;
+                                        reg.calls_for_fingerprint(&client_fp)
+                                            .iter()
+                                            .map(|c| (c.call_id.clone(), if c.caller_fingerprint == client_fp {
+                                                c.callee_fingerprint.clone()
+                                            } else {
+                                                c.caller_fingerprint.clone()
+                                            }))
+                                            .collect::<Vec<_>>()
+                                    };
+                                    for (call_id, peer_fp) in &calls {
+                                        let hub = signal_hub.lock().await;
+                                        let _ = hub.send_to(peer_fp, &msg).await;
+                                        drop(hub);
+                                        let mut reg = call_registry.lock().await;
+                                        reg.end_call(call_id);
+                                    }
+                                }
+
+                                SignalMessage::Ping { timestamp_ms } => {
+                                    let _ = transport.send_signal(&SignalMessage::Pong { timestamp_ms }).await;
+                                }
+
+                                other => {
+                                    warn!(%addr, "signal: unexpected message: {:?}", std::mem::discriminant(&other));
+                                }
+                            }
+                        }
+                        Ok(None) => {
+                            info!(%addr, "signal connection closed");
+                            break;
+                        }
+                        Err(e) => {
+                            warn!(%addr, "signal recv error: {e}");
+                            break;
+                        }
+                    }
+                }
+
+                // Cleanup: unregister + end active calls
+                let active_calls = {
+                    let reg = call_registry.lock().await;
+                    reg.calls_for_fingerprint(&client_fp)
+                        .iter()
+                        .map(|c| (c.call_id.clone(), if c.caller_fingerprint == client_fp {
+                            c.callee_fingerprint.clone()
+                        } else {
+                            c.caller_fingerprint.clone()
+                        }))
+                        .collect::<Vec<_>>()
+                };
+                for (call_id, peer_fp) in &active_calls {
+                    let hub = signal_hub.lock().await;
+                    let _ = hub.send_to(peer_fp, &SignalMessage::Hangup {
+                        reason: wzp_proto::HangupReason::Normal,
+                    }).await;
+                    drop(hub);
+                    let mut reg = call_registry.lock().await;
+                    reg.end_call(call_id);
+                }
+
+                {
+                    let mut hub = signal_hub.lock().await;
+                    hub.unregister(&client_fp);
+                }
+                {
+                    let mut reg = presence.lock().await;
+                    reg.unregister_local(&client_fp);
+                }
+
+                transport.close().await.ok();
+                return;
+            }
+
             // Auth check: if --auth-url is set, expect first signal message to be a token
             // Auth: if --auth-url is set, expect AuthToken as first signal
             let authenticated_fp: Option<String> = if let Some(ref url) = auth_url {
@@ -596,6 +965,28 @@ async fn main() -> anyhow::Result<()> {
             // Use the caller's identity fingerprint from the handshake
             let participant_fp = authenticated_fp.clone().unwrap_or(caller_fp);
 
+            // ACL: call rooms (call-*) are restricted to the two authorized participants.
+            // Only the relay's call orchestrator creates these rooms — random clients can't join.
+            if room_name.starts_with("call-") {
+                let call_id = &room_name[5..]; // strip "call-" prefix
+                let authorized = {
+                    let reg = call_registry.lock().await;
+                    match reg.get(call_id) {
+                        Some(call) => {
+                            call.caller_fingerprint == participant_fp
+                                || call.callee_fingerprint == participant_fp
+                        }
+                        None => false, // unknown call — reject
+                    }
+                };
+                if !authorized {
+                    warn!(%addr, room = %room_name, fp = %participant_fp, "rejected: not authorized for this call room");
+                    transport.close().await.ok();
+                    return;
+                }
+                info!(%addr, room = %room_name, fp = %participant_fp, "authorized for call room");
+            }
+
             // Register in presence registry
             {
                 let mut reg = presence.lock().await;
@@ -648,6 +1039,20 @@ async fn main() -> anyhow::Result<()> {
 
                 metrics.active_sessions.inc();
 
+                // Call rooms: enforce 2-participant limit
+                if room_name.starts_with("call-") {
+                    let mgr = room_mgr.lock().await;
+                    if mgr.room_size(&room_name) >= 2 {
+                        drop(mgr);
+                        warn!(%addr, room = %room_name, "call room full (max 2 participants)");
+                        metrics.active_sessions.dec();
+                        let mut smgr = session_mgr.lock().await;
+                        smgr.remove_session(session_id);
+                        transport.close().await.ok();
+                        return;
+                    }
+                }
+
                 let participant_id = {
                     let mut mgr = room_mgr.lock().await;
                     match mgr.join(
@@ -660,7 +1065,25 @@ async fn main() -> anyhow::Result<()> {
                         Ok((id, update, senders)) => {
                             metrics.active_rooms.set(mgr.list().len() as i64);
                             drop(mgr); // release lock before async broadcast
-                            room::broadcast_signal(&senders, &update).await;
+
+                            // Merge federated participants into RoomUpdate if this is a global room
+                            let merged_update = if let Some(ref fm) = federation_mgr {
+                                if fm.is_global_room(&room_name) {
+                                    if let SignalMessage::RoomUpdate { count: _, participants: mut local_parts } = update {
+                                        let remote = fm.get_remote_participants(&room_name).await;
+                                        local_parts.extend(remote);
+                                        // Deduplicate by fingerprint
+                                        let mut seen = std::collections::HashSet::new();
+                                        local_parts.retain(|p| seen.insert(p.fingerprint.clone()));
+                                        SignalMessage::RoomUpdate {
+                                            count: local_parts.len() as u32,
+                                            participants: local_parts,
+                                        }
+                                    } else { update }
+                                } else { update }
+                            } else { update };
+
+                            room::broadcast_signal(&senders, &merged_update).await;
                             id
                         }
                         Err(e) => {
@@ -678,6 +1101,25 @@ async fn main() -> anyhow::Result<()> {
                     .iter()
                     .map(|b| format!("{b:02x}"))
                     .collect();
+                // Set up federation media channel if this is a global room
+                let (federation_tx, federation_room_hash) = if let Some(ref fm) = federation_mgr {
+                    let is_global = fm.is_global_room(&room_name);
+                    if is_global {
+                        let canonical_hash = fm.global_room_hash(&room_name);
+                        let (tx, rx) = tokio::sync::mpsc::channel(256);
+                        let fm_clone = fm.clone();
+                        tokio::spawn(async move {
+                            wzp_relay::federation::run_federation_media_egress(fm_clone, rx).await;
+                        });
+                        info!(room = %room_name, canonical = ?fm.resolve_global_room(&room_name), "federation egress created (global room)");
+                        (Some(tx), Some(canonical_hash))
+                    } else {
+                        (None, None)
+                    }
+                } else {
+                    (None, None)
+                };
+
                 room::run_participant(
                     room_mgr.clone(),
                     room_name,
@@ -686,6 +1128,9 @@ async fn main() -> anyhow::Result<()> {
                     metrics.clone(),
                     &session_id_str,
                     trunking_enabled,
+                    debug_tap,
+                    federation_tx,
+                    federation_room_hash,
                 ).await;
 
                 // Participant disconnected — clean up presence + per-session metrics

crates/wzp-relay/src/metrics.rs

@@ -16,6 +16,13 @@ pub struct RelayMetrics {
     pub bytes_forwarded: IntCounter,
     pub auth_attempts: IntCounterVec,
     pub handshake_duration: Histogram,
+    // Federation metrics
+    pub federation_peer_status: IntGaugeVec,
+    pub federation_peer_rtt_ms: GaugeVec,
+    pub federation_packets_forwarded: IntCounterVec,
+    pub federation_packets_deduped: IntCounter,
+    pub federation_packets_rate_limited: IntCounter,
+    pub federation_active_rooms: IntGauge,
     // Per-session metrics
     pub session_buffer_depth: IntGaugeVec,
     pub session_loss_pct: GaugeVec,
@@ -60,6 +67,28 @@ impl RelayMetrics {
         )
         .expect("metric");
 
+        let federation_peer_status = IntGaugeVec::new(
+            Opts::new("wzp_federation_peer_status", "Peer connection status (0=disconnected, 1=connected)"),
+            &["peer"],
+        ).expect("metric");
+        let federation_peer_rtt_ms = GaugeVec::new(
+            Opts::new("wzp_federation_peer_rtt_ms", "QUIC RTT to federated peer in milliseconds"),
+            &["peer"],
+        ).expect("metric");
+        let federation_packets_forwarded = IntCounterVec::new(
+            Opts::new("wzp_federation_packets_forwarded_total", "Packets forwarded to/from federated peers"),
+            &["peer", "direction"],
+        ).expect("metric");
+        let federation_packets_deduped = IntCounter::with_opts(
+            Opts::new("wzp_federation_packets_deduped_total", "Duplicate federation packets dropped"),
+        ).expect("metric");
+        let federation_packets_rate_limited = IntCounter::with_opts(
+            Opts::new("wzp_federation_packets_rate_limited_total", "Federation packets dropped by rate limiter"),
+        ).expect("metric");
+        let federation_active_rooms = IntGauge::with_opts(
+            Opts::new("wzp_federation_active_rooms", "Number of federated rooms currently active"),
+        ).expect("metric");
+
         let session_buffer_depth = IntGaugeVec::new(
             Opts::new(
                 "wzp_relay_session_jitter_buffer_depth",
@@ -107,6 +136,12 @@ impl RelayMetrics {
         registry.register(Box::new(bytes_forwarded.clone())).expect("register");
         registry.register(Box::new(auth_attempts.clone())).expect("register");
         registry.register(Box::new(handshake_duration.clone())).expect("register");
+        registry.register(Box::new(federation_peer_status.clone())).expect("register");
+        registry.register(Box::new(federation_peer_rtt_ms.clone())).expect("register");
+        registry.register(Box::new(federation_packets_forwarded.clone())).expect("register");
+        registry.register(Box::new(federation_packets_deduped.clone())).expect("register");
+        registry.register(Box::new(federation_packets_rate_limited.clone())).expect("register");
+        registry.register(Box::new(federation_active_rooms.clone())).expect("register");
         registry.register(Box::new(session_buffer_depth.clone())).expect("register");
         registry.register(Box::new(session_loss_pct.clone())).expect("register");
         registry.register(Box::new(session_rtt_ms.clone())).expect("register");
@@ -120,6 +155,12 @@ impl RelayMetrics {
             bytes_forwarded,
             auth_attempts,
             handshake_duration,
+            federation_peer_status,
+            federation_peer_rtt_ms,
+            federation_packets_forwarded,
+            federation_packets_deduped,
+            federation_packets_rate_limited,
+            federation_active_rooms,
             session_buffer_depth,
             session_loss_pct,
             session_rtt_ms,

crates/wzp-relay/src/room.rs

@@ -18,6 +18,38 @@ use wzp_proto::MediaTransport;
 use crate::metrics::RelayMetrics;
 use crate::trunk::TrunkBatcher;
 
+/// Debug tap: logs packet metadata for matching rooms.
+#[derive(Clone)]
+pub struct DebugTap {
+    /// Room name filter ("*" = all rooms, or specific room name/hash).
+    pub room_filter: String,
+}
+
+impl DebugTap {
+    pub fn matches(&self, room_name: &str) -> bool {
+        self.room_filter == "*" || self.room_filter == room_name
+    }
+
+    pub fn log_packet(&self, room: &str, dir: &str, addr: &std::net::SocketAddr, pkt: &wzp_proto::MediaPacket, fan_out: usize) {
+        let h = &pkt.header;
+        info!(
+            target: "debug_tap",
+            room = %room,
+            dir = dir,
+            addr = %addr,
+            seq = h.seq,
+            codec = ?h.codec_id,
+            ts = h.timestamp,
+            fec_block = h.fec_block,
+            fec_sym = h.fec_symbol,
+            repair = h.is_repair,
+            len = pkt.payload.len(),
+            fan_out,
+            "TAP"
+        );
+    }
+}
+
 /// Unique participant ID within a room.
 pub type ParticipantId = u64;
 
@@ -27,13 +59,20 @@ fn next_id() -> ParticipantId {
     NEXT_PARTICIPANT_ID.fetch_add(1, Ordering::Relaxed)
 }
 
-/// Tracks where a participant originates from (for loop prevention).
-#[derive(Clone, Debug, PartialEq, Eq)]
-pub enum ParticipantOrigin {
-    /// Connected directly to this relay.
-    Local,
-    /// Virtual participant representing a federated peer relay.
-    Federated { relay_addr: std::net::SocketAddr },
+/// Events emitted by RoomManager for federation to observe.
+#[derive(Clone, Debug)]
+pub enum RoomEvent {
+    /// First local participant joined this room.
+    LocalJoin { room: String },
+    /// Last local participant left this room.
+    LocalLeave { room: String },
+}
+
+/// Outbound federation media from a local participant.
+pub struct FederationMediaOut {
+    pub room_name: String,
+    pub room_hash: [u8; 8],
+    pub data: Bytes,
 }
 
 /// How to send data to a participant — either via QUIC transport or WebSocket channel.
@@ -41,11 +80,6 @@ pub enum ParticipantOrigin {
 pub enum ParticipantSender {
     Quic(Arc<wzp_transport::QuinnTransport>),
     WebSocket(tokio::sync::mpsc::Sender<Bytes>),
-    /// Federated peer relay — media is prefixed with an 8-byte room hash.
-    Federation {
-        transport: Arc<wzp_transport::QuinnTransport>,
-        room_hash: [u8; 8],
-    },
 }
 
 impl ParticipantSender {
@@ -64,14 +98,6 @@ impl ParticipantSender {
                 };
                 transport.send_media(&pkt).await.map_err(|e| format!("quic send: {e}"))
             }
-            ParticipantSender::Federation { transport, room_hash } => {
-                // Prefix media data with room hash for demuxing on the peer relay
-                let mut tagged = Vec::with_capacity(8 + data.len());
-                tagged.extend_from_slice(room_hash);
-                tagged.extend_from_slice(data);
-                transport.send_raw_datagram(&tagged)
-                    .map_err(|e| format!("federation send: {e}"))
-            }
         }
     }
 
@@ -107,21 +133,17 @@ struct Participant {
     sender: ParticipantSender,
     fingerprint: Option<String>,
     alias: Option<String>,
-    origin: ParticipantOrigin,
 }
 
 /// A room holding multiple participants.
 struct Room {
     participants: Vec<Participant>,
-    /// Remote participants from federated peers (for merged RoomUpdate).
-    federated_participants: HashMap<std::net::SocketAddr, Vec<wzp_proto::packet::RoomParticipant>>,
 }
 
 impl Room {
     fn new() -> Self {
         Self {
             participants: Vec::new(),
-            federated_participants: HashMap::new(),
         }
     }
 
@@ -131,11 +153,10 @@ impl Room {
         sender: ParticipantSender,
         fingerprint: Option<String>,
         alias: Option<String>,
-        origin: ParticipantOrigin,
     ) -> ParticipantId {
         let id = next_id();
-        info!(room_size = self.participants.len() + 1, participant = id, %addr, ?origin, "joined room");
-        self.participants.push(Participant { id, _addr: addr, sender, fingerprint, alias, origin });
+        info!(room_size = self.participants.len() + 1, participant = id, %addr, "joined room");
+        self.participants.push(Participant { id, _addr: addr, sender, fingerprint, alias });
         id
     }
 
@@ -152,38 +173,16 @@ impl Room {
             .collect()
     }
 
-    /// Get senders with loop prevention for federation.
-    ///
-    /// - Media from a **local** participant → send to ALL others (local + federated)
-    /// - Media from a **federated** participant → send to LOCAL participants only
-    ///   (the source relay already forwarded to its own locals and other peers)
-    fn others_for_origin(&self, exclude_id: ParticipantId, source_origin: &ParticipantOrigin) -> Vec<ParticipantSender> {
+    /// Build a RoomUpdate participant list.
+    fn participant_list(&self) -> Vec<wzp_proto::packet::RoomParticipant> {
         self.participants
             .iter()
-            .filter(|p| p.id != exclude_id)
-            .filter(|p| match source_origin {
-                ParticipantOrigin::Local => true,
-                ParticipantOrigin::Federated { .. } => p.origin == ParticipantOrigin::Local,
-            })
-            .map(|p| p.sender.clone())
-            .collect()
-    }
-
-    /// Build a RoomUpdate participant list (local + federated).
-    fn participant_list(&self) -> Vec<wzp_proto::packet::RoomParticipant> {
-        let mut list: Vec<_> = self.participants
-            .iter()
-            .filter(|p| p.origin == ParticipantOrigin::Local)
             .map(|p| wzp_proto::packet::RoomParticipant {
                 fingerprint: p.fingerprint.clone().unwrap_or_default(),
                 alias: p.alias.clone(),
+                relay_label: None, // local participant
             })
-            .collect();
-        // Merge federated participants from all peer relays
-        for remote in self.federated_participants.values() {
-            list.extend(remote.iter().cloned());
-        }
-        list
+            .collect()
     }
 
     /// Get all senders (for broadcasting to everyone including the joiner).
@@ -207,24 +206,35 @@ pub struct RoomManager {
     /// When `None`, rooms are open (no auth mode). When `Some`, only listed
     /// fingerprints can join the corresponding room.
     acl: Option<HashMap<String, HashSet<String>>>,
+    /// Channel for room lifecycle events (federation subscribes).
+    event_tx: tokio::sync::broadcast::Sender<RoomEvent>,
 }
 
 impl RoomManager {
     pub fn new() -> Self {
+        let (event_tx, _) = tokio::sync::broadcast::channel(64);
         Self {
             rooms: HashMap::new(),
             acl: None,
+            event_tx,
         }
     }
 
     /// Create a room manager with ACL enforcement enabled.
     pub fn with_acl() -> Self {
+        let (event_tx, _) = tokio::sync::broadcast::channel(64);
         Self {
             rooms: HashMap::new(),
             acl: Some(HashMap::new()),
+            event_tx,
         }
     }
 
+    /// Subscribe to room lifecycle events (for federation).
+    pub fn subscribe_events(&self) -> tokio::sync::broadcast::Receiver<RoomEvent> {
+        self.event_tx.subscribe()
+    }
+
     /// Grant a fingerprint access to a room.
     pub fn allow(&mut self, room_name: &str, fingerprint: &str) {
         if let Some(ref mut acl) = self.acl {
@@ -263,8 +273,13 @@ impl RoomManager {
             warn!(room = room_name, fingerprint = ?fingerprint, "unauthorized room join attempt");
             return Err("not authorized for this room".to_string());
         }
+        let was_empty = !self.rooms.contains_key(room_name)
+            || self.rooms.get(room_name).map_or(true, |r| r.is_empty());
         let room = self.rooms.entry(room_name.to_string()).or_insert_with(Room::new);
-        let id = room.add(addr, sender, fingerprint.map(|s| s.to_string()), alias.map(|s| s.to_string()), ParticipantOrigin::Local);
+        let id = room.add(addr, sender, fingerprint.map(|s| s.to_string()), alias.map(|s| s.to_string()));
+        if was_empty {
+            let _ = self.event_tx.send(RoomEvent::LocalJoin { room: room_name.to_string() });
+        }
         let update = wzp_proto::SignalMessage::RoomUpdate {
             count: room.len() as u32,
             participants: room.participant_list(),
@@ -285,78 +300,22 @@ impl RoomManager {
         Ok(id)
     }
 
-    /// Join a room as a federated virtual participant.
-    pub fn join_federated(
-        &mut self,
-        room_name: &str,
-        relay_addr: std::net::SocketAddr,
-        sender: ParticipantSender,
-        remote_participants: Vec<wzp_proto::packet::RoomParticipant>,
-    ) -> (ParticipantId, wzp_proto::SignalMessage, Vec<ParticipantSender>) {
-        let room = self.rooms.entry(room_name.to_string()).or_insert_with(Room::new);
-        room.federated_participants.insert(relay_addr, remote_participants);
-        let id = room.add(
-            relay_addr, sender, None, Some("(federated)".to_string()),
-            ParticipantOrigin::Federated { relay_addr },
-        );
-        let update = wzp_proto::SignalMessage::RoomUpdate {
-            count: room.len() as u32,
-            participants: room.participant_list(),
-        };
-        let senders = room.all_senders();
-        (id, update, senders)
-    }
-
-    /// Update federated participant list for a room (from FederationParticipantUpdate).
-    pub fn update_federated_participants(
-        &mut self,
-        room_name: &str,
-        relay_addr: std::net::SocketAddr,
-        participants: Vec<wzp_proto::packet::RoomParticipant>,
-    ) -> Option<(wzp_proto::SignalMessage, Vec<ParticipantSender>)> {
-        if let Some(room) = self.rooms.get_mut(room_name) {
-            room.federated_participants.insert(relay_addr, participants);
-            let update = wzp_proto::SignalMessage::RoomUpdate {
-                count: room.len() as u32,
-                participants: room.participant_list(),
-            };
-            let senders = room.all_senders();
-            Some((update, senders))
-        } else {
-            None
-        }
-    }
-
-    /// Get the origin of a participant by ID.
-    pub fn participant_origin(&self, room_name: &str, participant_id: ParticipantId) -> Option<ParticipantOrigin> {
-        self.rooms.get(room_name)
-            .and_then(|room| room.participants.iter().find(|p| p.id == participant_id))
-            .map(|p| p.origin.clone())
-    }
-
-    /// Get list of active room names (for federation room announcements).
+    /// Get list of active room names.
     pub fn active_rooms(&self) -> Vec<String> {
         self.rooms.keys().cloned().collect()
     }
 
-    /// Get local participant list for a room (excludes federated virtual participants).
-    pub fn local_participants(&self, room_name: &str) -> Vec<wzp_proto::packet::RoomParticipant> {
+    /// Get participant list for a room (fingerprint + alias).
+    pub fn local_participant_list(&self, room_name: &str) -> Vec<wzp_proto::packet::RoomParticipant> {
         self.rooms.get(room_name)
-            .map(|room| room.participants.iter()
-                .filter(|p| p.origin == ParticipantOrigin::Local)
-                .map(|p| wzp_proto::packet::RoomParticipant {
-                    fingerprint: p.fingerprint.clone().unwrap_or_default(),
-                    alias: p.alias.clone(),
-                })
-                .collect())
+            .map(|room| room.participant_list())
             .unwrap_or_default()
     }
 
-    /// Get senders for local-only participants in a room (for federation inbound media).
+    /// Get all senders for participants in a room (for federation inbound media delivery).
     pub fn local_senders(&self, room_name: &str) -> Vec<ParticipantSender> {
         self.rooms.get(room_name)
             .map(|room| room.participants.iter()
-                .filter(|p| p.origin == ParticipantOrigin::Local)
                 .map(|p| p.sender.clone())
                 .collect())
             .unwrap_or_default()
@@ -368,6 +327,7 @@ impl RoomManager {
             room.remove(participant_id);
             if room.is_empty() {
                 self.rooms.remove(room_name);
+                let _ = self.event_tx.send(RoomEvent::LocalLeave { room: room_name.to_string() });
                 info!(room = room_name, "room closed (empty)");
                 return None;
             }
@@ -477,6 +437,9 @@ pub async fn run_participant(
     metrics: Arc<RelayMetrics>,
     session_id: &str,
     trunking_enabled: bool,
+    debug_tap: Option<DebugTap>,
+    federation_tx: Option<tokio::sync::mpsc::Sender<FederationMediaOut>>,
+    federation_room_hash: Option<[u8; 8]>,
 ) {
     if trunking_enabled {
         run_participant_trunked(
@@ -485,7 +448,7 @@ pub async fn run_participant(
         .await;
     } else {
         run_participant_plain(
-            room_mgr, room_name, participant_id, transport, metrics, session_id,
+            room_mgr, room_name, participant_id, transport, metrics, session_id, debug_tap, federation_tx, federation_room_hash,
         )
         .await;
     }
@@ -499,6 +462,9 @@ async fn run_participant_plain(
     transport: Arc<wzp_transport::QuinnTransport>,
     metrics: Arc<RelayMetrics>,
     session_id: &str,
+    debug_tap: Option<DebugTap>,
+    federation_tx: Option<tokio::sync::mpsc::Sender<FederationMediaOut>>,
+    federation_room_hash: Option<[u8; 8]>,
 ) {
     let addr = transport.connection().remote_address();
     let mut packets_forwarded = 0u64;
@@ -572,6 +538,13 @@ async fn run_participant_plain(
             );
         }
 
+        // Debug tap: log packet metadata
+        if let Some(ref tap) = debug_tap {
+            if tap.matches(&room_name) {
+                tap.log_packet(&room_name, "in", &addr, &pkt, others.len());
+            }
+        }
+
         // Forward to all others
         let fwd_start = std::time::Instant::now();
         let pkt_bytes = pkt.payload.len() as u64;
@@ -594,21 +567,19 @@ async fn run_participant_plain(
                 ParticipantSender::WebSocket(_) => {
                     let _ = other.send_raw(&pkt.payload).await;
                 }
-                ParticipantSender::Federation { transport, room_hash } => {
-                    // Send room-tagged datagram to federated peer
+            }
+        }
+
+        // Federation: forward to active peer relays via channel
+        if let Some(ref fed_tx) = federation_tx {
             let data = pkt.to_bytes();
-                    let mut tagged = Vec::with_capacity(8 + data.len());
-                    tagged.extend_from_slice(room_hash);
-                    tagged.extend_from_slice(&data);
-                    if let Err(e) = transport.send_raw_datagram(&tagged) {
-                        send_errors += 1;
-                        if send_errors <= 5 {
-                            warn!(room = %room_name, "federation forward error: {e}");
-                        }
-                    }
-                }
-            }
+            let _ = fed_tx.try_send(FederationMediaOut {
+                room_name: room_name.clone(),
+                room_hash: federation_room_hash.unwrap_or_else(|| crate::federation::room_hash(&room_name)),
+                data,
+            });
         }
+
         let fwd_ms = fwd_start.elapsed().as_millis() as u64;
         if fwd_ms > max_forward_ms {
             max_forward_ms = fwd_ms;
@@ -774,13 +745,6 @@ async fn run_participant_trunked(
                         ParticipantSender::WebSocket(_) => {
                             let _ = other.send_raw(&pkt.payload).await;
                         }
-                        ParticipantSender::Federation { transport, room_hash } => {
-                            let data = pkt.to_bytes();
-                            let mut tagged = Vec::with_capacity(8 + data.len());
-                            tagged.extend_from_slice(room_hash);
-                            tagged.extend_from_slice(&data);
-                            let _ = transport.send_raw_datagram(&tagged);
-                        }
                     }
                 }
                 let fwd_ms = fwd_start.elapsed().as_millis() as u64;

crates/wzp-relay/src/signal_hub.rs

@@ -0,0 +1,105 @@
+//! Persistent signaling connection manager.
+//!
+//! Tracks clients connected via `_signal` SNI. Routes call signals
+//! (DirectCallOffer, DirectCallAnswer, Hangup) between registered users.
+
+use std::collections::HashMap;
+use std::sync::Arc;
+use std::time::Instant;
+
+use tracing::{info, warn};
+use wzp_proto::{MediaTransport, SignalMessage};
+use wzp_transport::QuinnTransport;
+
+/// A client connected via `_signal` for direct calling.
+pub struct SignalClient {
+    pub fingerprint: String,
+    pub alias: Option<String>,
+    pub transport: Arc<QuinnTransport>,
+    pub connected_at: Instant,
+}
+
+/// Manages persistent signaling connections.
+pub struct SignalHub {
+    clients: HashMap<String, SignalClient>,
+}
+
+impl SignalHub {
+    pub fn new() -> Self {
+        Self {
+            clients: HashMap::new(),
+        }
+    }
+
+    /// Register a new signaling client.
+    pub fn register(&mut self, fp: String, transport: Arc<QuinnTransport>, alias: Option<String>) {
+        info!(fingerprint = %fp, alias = ?alias, "signal client registered");
+        self.clients.insert(fp.clone(), SignalClient {
+            fingerprint: fp,
+            alias,
+            transport,
+            connected_at: Instant::now(),
+        });
+    }
+
+    /// Unregister a signaling client. Returns the client if found.
+    pub fn unregister(&mut self, fp: &str) -> Option<SignalClient> {
+        let client = self.clients.remove(fp);
+        if client.is_some() {
+            info!(fingerprint = %fp, "signal client unregistered");
+        }
+        client
+    }
+
+    /// Look up a client by fingerprint.
+    pub fn get(&self, fp: &str) -> Option<&SignalClient> {
+        self.clients.get(fp)
+    }
+
+    /// Check if a fingerprint is online.
+    pub fn is_online(&self, fp: &str) -> bool {
+        self.clients.contains_key(fp)
+    }
+
+    /// Send a signal message to a client by fingerprint.
+    pub async fn send_to(&self, fp: &str, msg: &SignalMessage) -> Result<(), String> {
+        match self.clients.get(fp) {
+            Some(client) => {
+                client.transport.send_signal(msg).await
+                    .map_err(|e| format!("send to {fp}: {e}"))
+            }
+            None => Err(format!("{fp} not online")),
+        }
+    }
+
+    /// Number of connected signaling clients.
+    pub fn online_count(&self) -> usize {
+        self.clients.len()
+    }
+
+    /// List all online fingerprints.
+    pub fn online_fingerprints(&self) -> Vec<&str> {
+        self.clients.keys().map(|s| s.as_str()).collect()
+    }
+
+    /// Get alias for a fingerprint.
+    pub fn alias(&self, fp: &str) -> Option<&str> {
+        self.clients.get(fp).and_then(|c| c.alias.as_deref())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn register_unregister() {
+        let mut hub = SignalHub::new();
+        assert_eq!(hub.online_count(), 0);
+        assert!(!hub.is_online("alice"));
+
+        // Can't easily construct QuinnTransport in a unit test,
+        // so we just test the HashMap logic conceptually.
+        // Integration tests cover the full flow.
+    }
+}

crates/wzp-transport/src/quic.rs

@@ -143,7 +143,7 @@ impl MediaTransport for QuinnTransport {
             }
         };
 
-        match datagram::deserialize_media(data) {
+        match datagram::deserialize_media(data.clone()) {
             Some(packet) => {
                 // Record receive observation
                 {
@@ -156,8 +156,10 @@ impl MediaTransport for QuinnTransport {
                 Ok(Some(packet))
             }
             None => {
-                tracing::warn!("received malformed media datagram");
-                Ok(None)
+                tracing::warn!(len = data.len(), "skipping malformed media datagram, continuing");
+                // Don't return Ok(None) — that signals connection closed.
+                // Recurse to read the next datagram instead.
+                Box::pin(self.recv_media()).await
             }
         }
     }

docs/ADMINISTRATION.md

@@ -0,0 +1,747 @@
+# WarzonePhone Relay Administration Guide
+
+This document covers deploying, configuring, and operating wzp-relay instances, including federation setup, monitoring, and troubleshooting.
+
+## Relay Deployment
+
+### Binary
+
+Build and run the relay directly:
+
+```bash
+# Build release binary
+cargo build --release --bin wzp-relay
+
+# Run with defaults (listen on 0.0.0.0:4433, room mode, no auth)
+./target/release/wzp-relay
+
+# Run with config file
+./target/release/wzp-relay --config /etc/wzp/relay.toml
+```
+
+### Remote Build (Linux)
+
+The included build script provisions a temporary Hetzner Cloud VPS, builds all binaries, and downloads them:
+
+```bash
+# Requires: hcloud CLI authenticated, SSH key "wz" registered
+./scripts/build-linux.sh
+# Outputs to: target/linux-x86_64/
+```
+
+Produces: `wzp-relay`, `wzp-client`, `wzp-client-audio`, `wzp-web`, `wzp-bench`.
+
+### Docker
+
+```dockerfile
+FROM rust:1.85 AS builder
+WORKDIR /src
+COPY . .
+RUN cargo build --release --bin wzp-relay
+
+FROM debian:bookworm-slim
+RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
+COPY --from=builder /src/target/release/wzp-relay /usr/local/bin/
+EXPOSE 4433/udp
+EXPOSE 9090/tcp
+VOLUME /data
+ENV HOME=/data
+ENTRYPOINT ["wzp-relay"]
+CMD ["--config", "/data/relay.toml", "--metrics-port", "9090"]
+```
+
+Build and run:
+
+```bash
+docker build -t wzp-relay .
+docker run -d \
+  --name wzp-relay \
+  -p 4433:4433/udp \
+  -p 9090:9090/tcp \
+  -v /opt/wzp:/data \
+  wzp-relay
+```
+
+### systemd
+
+Create `/etc/systemd/system/wzp-relay.service`:
+
+```ini
+[Unit]
+Description=WarzonePhone Relay
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=wzp
+Group=wzp
+ExecStart=/usr/local/bin/wzp-relay --config /etc/wzp/relay.toml
+Restart=always
+RestartSec=5
+LimitNOFILE=65536
+
+# Security hardening
+NoNewPrivileges=yes
+ProtectSystem=strict
+ProtectHome=yes
+ReadWritePaths=/var/lib/wzp
+PrivateTmp=yes
+
+Environment=HOME=/var/lib/wzp
+Environment=RUST_LOG=info
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Setup:
+
+```bash
+# Create service user
+useradd --system --home-dir /var/lib/wzp --create-home wzp
+
+# Install binary and config
+cp target/release/wzp-relay /usr/local/bin/
+mkdir -p /etc/wzp
+cp relay.toml /etc/wzp/
+
+# Enable and start
+systemctl daemon-reload
+systemctl enable --now wzp-relay
+journalctl -u wzp-relay -f
+```
+
+## TOML Configuration Reference
+
+All fields have defaults. A minimal config file only needs the fields you want to override.
+
+### Core Settings
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `listen_addr` | string (socket addr) | `"0.0.0.0:4433"` | UDP address to listen on for incoming QUIC connections |
+| `remote_relay` | string (socket addr) | none | Remote relay address for forward mode. Disables room mode when set |
+| `max_sessions` | integer | `100` | Maximum concurrent client sessions |
+| `log_level` | string | `"info"` | Logging level: trace, debug, info, warn, error |
+
+### Jitter Buffer
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `jitter_target_depth` | integer | `50` | Target buffer depth in packets (50 = 1 second at 20ms frames) |
+| `jitter_max_depth` | integer | `250` | Maximum buffer depth in packets (250 = 5 seconds) |
+
+### Authentication
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `auth_url` | string | none | featherChat auth validation URL. When set, clients must send a bearer token as their first signal message. The relay validates it via `POST <auth_url>` |
+
+### Metrics and Monitoring
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `metrics_port` | integer | none | Port for the Prometheus HTTP metrics endpoint. Disabled if not set |
+| `probe_targets` | array of socket addrs | `[]` | Peer relay addresses to probe for health monitoring (1 Ping/s each) |
+| `probe_mesh` | boolean | `false` | Enable mesh mode for probe targets |
+
+### Media Processing
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `trunking_enabled` | boolean | `false` | Enable trunk batching for outgoing media. Packs multiple session packets into one QUIC datagram, reducing overhead |
+
+### WebSocket / Browser Support
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `ws_port` | integer | none | Port for WebSocket listener (browser clients). Disabled if not set |
+| `static_dir` | string | none | Directory to serve static files (HTML/JS/WASM) |
+
+### Federation
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `peers` | array of PeerConfig | `[]` | Outbound federation peer relays |
+| `trusted` | array of TrustedConfig | `[]` | Inbound federation trust list |
+| `global_rooms` | array of GlobalRoomConfig | `[]` | Room names to bridge across federation |
+
+### Debugging
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `debug_tap` | string | none | Log packet headers for matching rooms. Use `"*"` for all rooms, or a specific room name |
+
+### PeerConfig Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `url` | string | yes | Address of the peer relay (e.g., `"193.180.213.68:4433"`) |
+| `fingerprint` | string | yes | Expected TLS certificate fingerprint (hex with colons) |
+| `label` | string | no | Human-readable label for logging |
+
+### TrustedConfig Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `fingerprint` | string | yes | Expected TLS certificate fingerprint (hex with colons) |
+| `label` | string | no | Human-readable label for logging |
+
+### GlobalRoomConfig Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | yes | Room name to bridge across federation (e.g., `"android"`) |
+
+## CLI Flags Reference
+
+```
+wzp-relay [--config <path>] [--listen <addr>] [--remote <addr>]
+          [--auth-url <url>] [--metrics-port <port>]
+          [--probe <addr>]... [--probe-mesh] [--mesh-status]
+          [--trunking] [--global-room <name>]...
+          [--debug-tap <room>]
+          [--ws-port <port>] [--static-dir <dir>]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--config <path>` | Load configuration from TOML file. CLI flags override config file values |
+| `--listen <addr>` | Listen address (default: `0.0.0.0:4433`) |
+| `--remote <addr>` | Remote relay for forwarding mode. Disables room mode |
+| `--auth-url <url>` | featherChat auth endpoint (e.g., `https://chat.example.com/v1/auth/validate`) |
+| `--metrics-port <port>` | Prometheus metrics HTTP port (e.g., `9090`) |
+| `--probe <addr>` | Peer relay to probe for health monitoring. Repeatable |
+| `--probe-mesh` | Enable mesh mode for probes |
+| `--mesh-status` | Print mesh health table and exit (diagnostic) |
+| `--trunking` | Enable trunk batching for outgoing media |
+| `--global-room <name>` | Declare a room as global (bridged across federation). Repeatable |
+| `--debug-tap <room>` | Log packet headers for a room (`"*"` for all rooms) |
+| `--event-log <path>` | Write JSONL protocol event log for federation debugging |
+| `--version`, `-V` | Print build git hash and exit |
+| `--ws-port <port>` | WebSocket listener port for browser clients |
+| `--static-dir <dir>` | Directory to serve static files from |
+| `--help`, `-h` | Print help and exit |
+
+CLI flags always override config file values when both are specified.
+
+## Federation Setup
+
+### Concepts
+
+- **`[[peers]]`** -- outbound: relays we connect TO. Requires address + fingerprint
+- **`[[trusted]]`** -- inbound: relays we accept connections FROM. Requires fingerprint only (they connect to us)
+- **`[[global_rooms]]`** -- rooms bridged across all federated peers. Participants on different relays in the same global room hear each other
+
+### Getting Your Relay's Fingerprint
+
+When a relay starts, it logs its TLS fingerprint:
+
+```
+INFO TLS certificate (deterministic from relay identity) tls_fingerprint="a5d6:e3c6:5ae7:185c:4eb1:af89:daed:4a43"
+INFO federation: to peer with this relay, add to relay.toml:
+INFO   [[peers]]
+INFO   url = "193.180.213.68:4433"
+INFO   fingerprint = "a5d6:e3c6:5ae7:185c:4eb1:af89:daed:4a43"
+```
+
+Share this information with the administrator of the peer relay.
+
+### Unknown Peer Connections
+
+When an unknown relay tries to federate, the log shows:
+
+```
+WARN unknown relay wants to federate addr=10.0.0.5:12345 fp="7f2a:b391:0c44:..."
+INFO   to accept, add to relay.toml:
+INFO   [[trusted]]
+INFO   fingerprint = "7f2a:b391:0c44:..."
+INFO   label = "Relay at 10.0.0.5:12345"
+```
+
+## Example Configurations
+
+### Single Relay (Minimal)
+
+```toml
+# /etc/wzp/relay.toml
+# Minimal config -- all defaults, just enable metrics
+metrics_port = 9090
+```
+
+Run:
+
+```bash
+wzp-relay --config /etc/wzp/relay.toml
+```
+
+### Single Relay (Full Featured)
+
+```toml
+# /etc/wzp/relay.toml
+listen_addr = "0.0.0.0:4433"
+max_sessions = 200
+log_level = "info"
+
+# Metrics
+metrics_port = 9090
+
+# Authentication
+auth_url = "https://chat.example.com/v1/auth/validate"
+
+# Browser support
+ws_port = 8080
+static_dir = "/opt/wzp/web"
+
+# Performance
+trunking_enabled = true
+
+# Jitter buffer tuning
+jitter_target_depth = 50
+jitter_max_depth = 250
+```
+
+### Two-Relay Federation
+
+**Relay A** (`relay-a.toml` on 193.180.213.68):
+
+```toml
+listen_addr = "0.0.0.0:4433"
+metrics_port = 9090
+
+# Outbound: connect to Relay B
+[[peers]]
+url = "10.0.0.5:4433"
+fingerprint = "7f2a:b391:0c44:9e1d:a8b2:c5d7:e3f0:1234"
+label = "Relay B (US)"
+
+# Accept inbound from Relay B
+[[trusted]]
+fingerprint = "7f2a:b391:0c44:9e1d:a8b2:c5d7:e3f0:1234"
+label = "Relay B (US)"
+
+# Bridge these rooms
+[[global_rooms]]
+name = "android"
+
+[[global_rooms]]
+name = "general"
+```
+
+**Relay B** (`relay-b.toml` on 10.0.0.5):
+
+```toml
+listen_addr = "0.0.0.0:4433"
+metrics_port = 9090
+
+# Outbound: connect to Relay A
+[[peers]]
+url = "193.180.213.68:4433"
+fingerprint = "a5d6:e3c6:5ae7:185c:4eb1:af89:daed:4a43"
+label = "Relay A (EU)"
+
+# Accept inbound from Relay A
+[[trusted]]
+fingerprint = "a5d6:e3c6:5ae7:185c:4eb1:af89:daed:4a43"
+label = "Relay A (EU)"
+
+# Same global rooms
+[[global_rooms]]
+name = "android"
+
+[[global_rooms]]
+name = "general"
+```
+
+### Three-Relay Chain (Full Mesh)
+
+For three relays (A, B, C) in full mesh federation, each relay needs peers and trusted entries for the other two:
+
+**Relay A** (EU):
+
+```toml
+listen_addr = "0.0.0.0:4433"
+metrics_port = 9090
+
+# Probe all peers
+probe_targets = ["10.0.0.5:4433", "10.0.0.9:4433"]
+probe_mesh = true
+
+# Peers
+[[peers]]
+url = "10.0.0.5:4433"
+fingerprint = "7f2a:b391:0c44:9e1d:a8b2:c5d7:e3f0:1234"
+label = "Relay B (US)"
+
+[[peers]]
+url = "10.0.0.9:4433"
+fingerprint = "3c8e:d2a1:f7b5:6049:81c3:e9d4:a2f6:5678"
+label = "Relay C (APAC)"
+
+# Trust
+[[trusted]]
+fingerprint = "7f2a:b391:0c44:9e1d:a8b2:c5d7:e3f0:1234"
+label = "Relay B (US)"
+
+[[trusted]]
+fingerprint = "3c8e:d2a1:f7b5:6049:81c3:e9d4:a2f6:5678"
+label = "Relay C (APAC)"
+
+# Global rooms
+[[global_rooms]]
+name = "android"
+
+[[global_rooms]]
+name = "general"
+```
+
+**Relay B** and **Relay C** follow the same pattern, listing the other two relays in their `[[peers]]` and `[[trusted]]` sections.
+
+## Monitoring
+
+### Prometheus Metrics
+
+Enable with `--metrics-port <port>` or `metrics_port` in TOML. The relay exposes metrics at `GET /metrics` on the specified HTTP port.
+
+#### Relay Metrics
+
+| Metric | Type | Labels | Description |
+|--------|------|--------|-------------|
+| `wzp_relay_active_sessions` | Gauge | -- | Current active sessions |
+| `wzp_relay_active_rooms` | Gauge | -- | Current active rooms |
+| `wzp_relay_packets_forwarded_total` | Counter | `room` | Total packets forwarded |
+| `wzp_relay_bytes_forwarded_total` | Counter | `room` | Total bytes forwarded |
+| `wzp_relay_auth_attempts_total` | Counter | `result` (ok/fail) | Auth validation attempts |
+| `wzp_relay_handshake_duration_seconds` | Histogram | -- | Crypto handshake time |
+
+#### Per-Session Metrics
+
+| Metric | Type | Labels | Description |
+|--------|------|--------|-------------|
+| `wzp_relay_session_jitter_buffer_depth` | Gauge | `session_id` | Buffer depth per session |
+| `wzp_relay_session_loss_pct` | Gauge | `session_id` | Packet loss percentage |
+| `wzp_relay_session_rtt_ms` | Gauge | `session_id` | Round-trip time |
+| `wzp_relay_session_underruns_total` | Counter | `session_id` | Jitter buffer underruns |
+| `wzp_relay_session_overruns_total` | Counter | `session_id` | Jitter buffer overruns |
+
+#### Inter-Relay Probe Metrics
+
+| Metric | Type | Labels | Description |
+|--------|------|--------|-------------|
+| `wzp_probe_rtt_ms` | Gauge | `target` | RTT to peer relay |
+| `wzp_probe_loss_pct` | Gauge | `target` | Loss to peer relay |
+| `wzp_probe_jitter_ms` | Gauge | `target` | Jitter to peer relay |
+| `wzp_probe_up` | Gauge | `target` | 1 if reachable, 0 if not |
+
+### Prometheus Scrape Config
+
+```yaml
+# prometheus.yml
+scrape_configs:
+  - job_name: 'wzp-relay'
+    static_configs:
+      - targets:
+        - 'relay-a:9090'
+        - 'relay-b:9090'
+    scrape_interval: 10s
+```
+
+### Grafana Dashboard
+
+A pre-built dashboard is available at `docs/grafana-dashboard.json`. Import it into Grafana for:
+
+1. **Relay Health** -- active sessions, rooms, packets/s, bytes/s
+2. **Call Quality** -- per-session jitter depth, loss%, RTT, underruns over time
+3. **Inter-Relay Mesh** -- latency heatmap, probe status, loss trends
+4. **Web Bridge** -- active connections, frames bridged, auth failures
+
+### Event Log (Protocol Analyzer)
+
+Use `--event-log` to write a JSONL event log that traces every federation media packet through the relay pipeline. Essential for debugging federation audio issues.
+
+```bash
+wzp-relay --config relay.toml --event-log /tmp/events.jsonl
+```
+
+Each media packet emits events at every decision point:
+- `federation_ingress` — packet arrived from a peer relay
+- `local_deliver` — packet delivered to local participants
+- `dedup_drop` — packet dropped as duplicate
+- `rate_limit_drop` — packet dropped by rate limiter
+- `room_not_found` — packet for unknown room
+- `local_deliver_error` — delivery to local client failed
+
+Analyze with:
+```bash
+# Count events by type
+cat events.jsonl | python3 -c "
+import json, collections, sys
+c = collections.Counter()
+for l in sys.stdin: c[json.loads(l)['event']] += 1
+for k,v in sorted(c.items(), key=lambda x:-x[1]): print(f'  {k}: {v}')
+"
+```
+
+### Remote Version Check
+
+Verify a deployed relay's version without SSH:
+
+```bash
+wzp-client --version-check <relay-addr:port>
+```
+
+### Debug Tap
+
+Use `--debug-tap` to log packet headers for debugging:
+
+```bash
+# Log headers for room "android"
+wzp-relay --debug-tap android
+
+# Log headers for all rooms
+wzp-relay --debug-tap '*'
+```
+
+Or in TOML:
+
+```toml
+debug_tap = "android"
+```
+
+### Mesh Status
+
+Print the current mesh health table (diagnostic):
+
+```bash
+wzp-relay --mesh-status
+```
+
+## Authentication
+
+### featherChat Token Validation
+
+When `--auth-url` is set, the relay requires clients to send an `AuthToken` signal message as their first message after QUIC connection. The relay validates the token by calling:
+
+```
+POST <auth_url>
+Content-Type: application/json
+Authorization: Bearer <token>
+```
+
+Expected response:
+
+```json
+{
+  "valid": true,
+  "fingerprint": "a5d6:e3c6:...",
+  "alias": "username"
+}
+```
+
+If validation fails, the client is disconnected.
+
+### Without Authentication
+
+When `--auth-url` is not set, any client can connect. The relay logs:
+
+```
+INFO auth disabled -- any client can connect (use --auth-url to enable)
+```
+
+## Identity Persistence
+
+### Relay Identity File
+
+The relay stores its identity seed at `~/.wzp/relay-identity` (a 64-character hex string). This seed:
+
+- Is generated automatically on first run
+- Persists across restarts
+- Derives the relay's Ed25519 signing key and X25519 key agreement key
+- Derives the TLS certificate deterministically (same seed = same cert = same fingerprint)
+
+If the identity file is corrupted, the relay generates a new one and logs a warning. This will change the relay's TLS fingerprint, requiring federation peers to update their config.
+
+### Backup
+
+Back up the identity file to preserve the relay's fingerprint:
+
+```bash
+cp ~/.wzp/relay-identity /secure/backup/relay-identity
+```
+
+To restore, copy the file back before starting the relay.
+
+## Troubleshooting
+
+### Common Issues
+
+| Problem | Cause | Solution |
+|---------|-------|---------|
+| "unknown argument" on startup | Unrecognized CLI flag | Check `wzp-relay --help` for valid flags |
+| "failed to load config" | Invalid TOML syntax | Validate TOML file with `toml-cli` or similar |
+| "auth failed" for all clients | Wrong `auth_url` or featherChat server down | Verify URL is reachable: `curl -X POST <auth_url>` |
+| "session rejected" | Max sessions reached | Increase `max_sessions` in config |
+| Clients cannot connect | Firewall blocking UDP 4433 | Open UDP port 4433 in firewall |
+| Federation "unknown relay wants to federate" | Peer's fingerprint not in `[[trusted]]` | Add the logged fingerprint to `[[trusted]]` |
+| Federation "fingerprint mismatch" | Peer relay restarted with new identity | Update the fingerprint in `[[peers]]` config |
+| Federation audio silent on consecutive connects | Dedup filter or jitter buffer state | Verify relay is running latest build with time-based dedup |
+| Federation participant shows wrong relay label | Hub relay not propagating original labels | Update relay to latest build (label preservation fix) |
+| Federation disconnect takes >15 seconds | QUIC idle timeout + stale sweeper | Normal: sweeper runs every 5s with 15s TTL. Use latest client with SIGTERM handler for instant disconnect |
+| High packet loss between relays | Network congestion or misconfiguration | Check `wzp_probe_loss_pct` metric; consider relay chaining |
+| Jitter buffer overruns | Packets arriving faster than playout | Increase `jitter_max_depth` |
+| Jitter buffer underruns | Packets arriving too slowly or lost | Check network quality; increase `jitter_target_depth` |
+| "probe connection closed" | Peer relay unreachable or crashed | Check peer relay status; will auto-reconnect |
+| WebSocket clients cannot connect | `ws_port` not set | Add `--ws-port <port>` or `ws_port` in TOML |
+| Browser mic access denied | Not using HTTPS | Use TLS termination in front of the relay or serve via `wzp-web --tls` |
+
+### Log Level Tuning
+
+Set `RUST_LOG` environment variable for fine-grained control:
+
+```bash
+# All relay logs at debug level
+RUST_LOG=debug wzp-relay
+
+# Only federation at trace, everything else at info
+RUST_LOG=info,wzp_relay::federation=trace wzp-relay
+
+# Quiet mode -- only warnings and errors
+RUST_LOG=warn wzp-relay
+```
+
+### Health Checks
+
+```bash
+# Check if relay is listening
+nc -zu relay-host 4433
+
+# Check metrics endpoint
+curl -s http://relay-host:9090/metrics | head -20
+
+# Check active sessions
+curl -s http://relay-host:9090/metrics | grep wzp_relay_active_sessions
+
+# Check federation probe health
+curl -s http://relay-host:9090/metrics | grep wzp_probe_up
+```
+
+## Build Pipelines
+
+All production artifacts (Android APK, Linux x86_64 binaries, Windows `.exe`) are built on **SepehrHomeserverdk** using Docker, not on developer workstations. The pipelines are fire-and-forget: a local script invokes a `tmux` session on the remote, the build runs in a Docker container, and the artifact is uploaded to `paste.dk.manko.yoga` (rustypaste) with a notification sent to `ntfy.sh/wzp` on start and completion.
+
+### Docker images
+
+Two long-lived images live on the remote:
+
+| Image | Used by | Base | Key contents |
+|---|---|---|---|
+| `wzp-android-builder` | Android APK (Tauri mobile + legacy Kotlin), Linux x86_64 relay/CLI | Debian bookworm | Rust stable with Android targets, cargo-ndk, NDK 26.1, Android SDK (API 34 + 35 + 36), JDK 17, Gradle 8.5, Node.js 20, cmake, ninja, tauri-cli 2.x |
+| `wzp-windows-builder` | Windows x86_64 `.exe` | Debian bookworm | Rust stable with `x86_64-pc-windows-msvc` target, cargo-xwin (with pre-warmed MSVC CRT + Windows SDK cache), Node.js 20, cmake, ninja, clang, lld, nasm |
+
+Both images are rebuilt rarely — once the base toolchain is stable, rebuilds are only needed to pick up new dependencies or security patches.
+
+**Rebuilding an image** (fire-and-forget, ~10 min on a warm base):
+
+```bash
+# Windows
+./scripts/build-windows-docker.sh --image-build
+
+# Android (upload and rebuild handled by the Android build script itself — see
+# its --image-build flag or equivalent)
+```
+
+The `--image-build` flag uploads the local Dockerfile to the remote, kicks off `docker build` under `nohup`, and returns immediately. Monitor with:
+
+```bash
+ssh SepehrHomeserverdk 'tail -f /tmp/wzp-windows-image-build.log'
+```
+
+### Pipeline: Android APK (Tauri Mobile)
+
+```bash
+./scripts/build-tauri-android.sh                  # Full: pull + build + upload + notify
+./scripts/build-tauri-android.sh --no-pull        # Skip git fetch
+./scripts/build-tauri-android.sh --clean          # Force-clean Rust target
+```
+
+- **Branch**: `android-rewrite`
+- **Image**: `wzp-android-builder`
+- **Build command**: `cargo tauri android build --release`
+- **Output**: `wzp-release.apk` → uploaded to rustypaste
+- **Notifications**: start + completion to `ntfy.sh/wzp`
+- **Remote artifact path**: `/mnt/storage/manBuilder/data/cache-android/target/…/release/app-release.apk`
+
+### Pipeline: Linux x86_64 (relay + CLI + bench + web)
+
+```bash
+./scripts/build-linux-docker.sh                   # Fire-and-forget
+./scripts/build-linux-docker.sh --no-pull         # Skip git fetch
+./scripts/build-linux-docker.sh --clean           # Force-clean target
+./scripts/build-linux-docker.sh --install         # Wait for completion and download locally
+```
+
+- **Branch**: `feat/android-voip-client` (script default — override by editing the script or passing an env var)
+- **Image**: `wzp-android-builder` (shared, not a separate Linux-only image)
+- **Targets built**: `wzp-relay`, `wzp-client`, `wzp-client-audio` (with `--features audio`), `wzp-web`, `wzp-bench`
+- **Output**: `wzp-linux-x86_64.tar.gz` with all five binaries → uploaded to rustypaste
+- **Local landing dir** (with `--install`): `target/linux-x86_64/`
+
+### Pipeline: Windows x86_64 (`wzp-desktop.exe`)
+
+```bash
+./scripts/build-windows-docker.sh                 # Full: pull + build + download locally
+./scripts/build-windows-docker.sh --no-pull       # Skip git fetch
+./scripts/build-windows-docker.sh --rust          # Force-clean target-windows cache
+./scripts/build-windows-docker.sh --image-build   # Rebuild the Docker image (fire-and-forget)
+```
+
+- **Branch**: `feat/desktop-audio-rewrite`
+- **Image**: `wzp-windows-builder`
+- **Build command**: `cargo xwin build --release --target x86_64-pc-windows-msvc --bin wzp-desktop`
+- **Output**: `wzp-desktop.exe` (~16 MB) → downloaded to `target/windows-exe/wzp-desktop.exe`, also uploaded to rustypaste
+- **Target cache volume**: `target-windows` (separate from the Android target cache to avoid triple cross-contamination)
+- **Shared cache volumes**: `cargo-registry`, `cargo-git` (shared with Android — both pipelines pull the same crates)
+
+**A/B-preserving workflow** for testing audio backends: rename the prior `.exe` before re-running the build, so both coexist:
+
+```bash
+# Preserve prior build as the noAEC baseline
+mv target/windows-exe/wzp-desktop.exe target/windows-exe/wzp-desktop-noAEC.exe
+./scripts/build-windows-docker.sh
+ls -la target/windows-exe/
+# wzp-desktop-noAEC.exe  (previous build)
+# wzp-desktop.exe        (new build)
+```
+
+### Alternative pipeline: Windows via Hetzner Cloud VPS
+
+For situations where Docker image rebuilds would be disruptive, or for one-shot debug builds on a clean machine:
+
+```bash
+./scripts/build-windows-cloud.sh                  # Full: create VM → build → download → destroy
+./scripts/build-windows-cloud.sh --prepare        # Create VM + install deps, don't build
+./scripts/build-windows-cloud.sh --build          # Build on existing VM
+./scripts/build-windows-cloud.sh --transfer       # Download .exe from existing VM
+./scripts/build-windows-cloud.sh --destroy        # Delete the VM
+WZP_KEEP_VM=1 ./scripts/build-windows-cloud.sh    # Don't auto-destroy after successful build
+```
+
+- **Provider**: Hetzner Cloud
+- **Default server type**: `cx33` (8 GB RAM, 8 vCPU — `cx23` with 4 GB OOMs on the tauri+rustls cross-compile)
+- **Image**: `ubuntu-24.04`
+- **SSH key**: must be named `wz` in Hetzner and loaded in the local ssh-agent
+- **Reminder**: set `WZP_KEEP_VM=1` for multi-build sessions, then **remember to `--destroy` at end of day** so the VM isn't left running overnight. This is tracked in the auto-memory as `feedback_keep_windows_builder_vm.md`.
+
+### Notifications
+
+All pipelines post to `https://ntfy.sh/wzp`. Subscribe from your phone via the [ntfy.sh app](https://ntfy.sh/) to get push notifications on build start/success/failure. Messages include the short git hash and the rustypaste URL on success:
+
+```
+WZP Windows build OK [03a80a3] (16M)
+https://paste.dk.manko.yoga/<uuid>/wzp-desktop.exe
+```
+
+### Rustypaste credentials
+
+Build pipelines read `rusty_address` and `rusty_auth_token` from the `.env` file at `/mnt/storage/manBuilder/.env` on SepehrHomeserverdk. Local scripts that upload directly (`build-windows-cloud.sh` when run in `--transfer` mode) read from `~/.wzp/rustypaste.env` with the same variable names. Both files must be kept in sync manually if rotated.

docs/BRANCH-android-rewrite.md

@@ -0,0 +1,139 @@
+# Branch: `android-rewrite`
+
+Pivot away from the legacy Kotlin + JNI Android client to a pure-Rust **Tauri 2.x Mobile** app that shares the same frontend and backend code as the desktop client.
+
+## Why this branch exists
+
+The Kotlin + JNI stack was a crash factory. Every failure mode we hit was at the Kotlin ↔ Rust boundary, and each fix uncovered the next layer of the onion:
+
+| Symptom | Root cause | Fix |
+|---|---|---|
+| App crashed on launch before `onCreate` returned | `__init_tcb` / `pthread_create` bionic private symbols leaking out of `libwzp_android.so` because the Rust crate used `crate-type = ["cdylib", "staticlib"]`. rust-lang/rust#104707 documents that staticlib alongside cdylib leaks non-exported symbols from the staticlib into the cdylib, and Bionic's private internal pthread symbols got bound LOCALLY inside our `.so` instead of resolved against `libc.so` at `dlopen` time | Dropped `staticlib` from the crate-type list. `crate-type = ["cdylib", "rlib"]` only. |
+| Stack overflow on `place_call` | `Dispatchers.IO` threads have a ~512 KB stack, too small for the Rust signal-connect path that does TLS handshake + quinn setup inside one closure | Launched JNI calls from a dedicated `java.lang.Thread` with an explicit 8 MB stack |
+| `ring` / `libcrypto` TLS reuse crash on second call | tokio runtime got dropped between calls, but `ring` keeps a TLS-stored SSL context that is invalidated when the runtime thread is reused by a new runtime — `ring` sees stale context and segfaults | Single long-lived tokio runtime for the entire signal client lifetime; split `start()` into an inline `connect+register` path and a `run()` path on a separate thread to avoid the `thread::spawn` closure's stack overflow |
+| Null dereference on register with fresh install | Identity seed file empty when it existed-but-was-blank, Rust side deref'd the zero-length slice | Generate seed if empty on register |
+
+Every fix kept the app limping along but the fundamental design problem remained: **state management was split across a Kotlin ViewModel and a Rust engine, with a hand-rolled JNI bridge in between that had to be perfect to not crash**. The working desktop Tauri client (with the same Rust backend) had none of these problems because it spoke to the Rust code via in-process `invoke()` from a WebView, not JNI.
+
+So: rewrite the Android app as a **Tauri 2.x Mobile app**, reusing the entire desktop codebase verbatim (`main.ts`, `style.css`, `index.html`, `main.rs`, `engine.rs` — everything). Tauri Mobile added Android support in v2, it's production-ready, and it eliminates the JNI boundary entirely.
+
+The incident postmortem lives at [`docs/incident-tauri-android-init-tcb.md`](incident-tauri-android-init-tcb.md).
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│                Tauri 2.x Mobile                  │
+│                                                  │
+│  Android WebView  ──────────  HTML/JS/CSS       │  ← Shared with desktop
+│         │                      (main.ts)         │
+│         │                                        │
+│    invoke() ─────────────── Rust Commands       │  ← Shared with desktop
+│                             (main.rs)            │
+│                               │                  │
+│              ┌───────────────┼────────────┐     │
+│              │               │            │     │
+│         SignalMgr        CallEngine   Identity  │  ← Shared crates
+│        (signal_hub)     (wzp-client) (wzp-crypto)│
+│              │               │                  │
+│              │               │                  │
+│              ▼               ▼                  │
+│        QUIC to relay    Oboe audio (Android)    │
+│                         via wzp-native cdylib   │
+└─────────────────────────────────────────────────┘
+```
+
+**What is reused from desktop verbatim** (zero rewrite):
+
+- `desktop/src/main.ts` — entire frontend
+- `desktop/src/style.css` — all styling
+- `desktop/src/identicon.ts` — identicon rendering
+- `desktop/index.html` — HTML structure
+- `desktop/src-tauri/src/main.rs` — all Tauri commands (`connect`, `disconnect`, `register_signal`, `place_call`, …)
+- `desktop/src-tauri/src/engine.rs` — `CallEngine` wrapper
+
+**What is Android-specific**:
+
+- `desktop/src-tauri/src/android_audio.rs` — JVM-side audio routing (`AudioManager.setSpeakerphoneOn` for earpiece/speaker toggle). Runs from Tauri's existing JNI context — no hand-rolled bridge, Tauri owns the JVM hookup.
+- `desktop/src-tauri/src/wzp_native.rs` — runtime `dlopen` of `libwzp_native.so`, a standalone cdylib crate (`crates/wzp-native`) that owns all C++ (Oboe bridge). Kept in its own crate so its C/C++ static archives never get statically linked into `wzp-desktop`'s `.so`, which would re-trigger the `__init_tcb` / pthread leak.
+- `crates/wzp-native/` — the standalone C++/Oboe bridge cdylib. Loaded via `libloading` at runtime from `wzp_native.rs`. Provides capture + playout streams using Oboe's `Usage::VoiceCommunication` + `MODE_IN_COMMUNICATION` combo.
+- Android-specific target dependencies in `desktop/src-tauri/Cargo.toml` (`jni`, `ndk-context`, `libloading`) — no CPAL, no VPIO.
+
+## Key architectural decisions
+
+### 1. `wzp-native` as a standalone cdylib loaded via `libloading`
+
+The alternative — linking `wzp-native` as a regular Rust dep with C++ static archives — would cause the same `__init_tcb` crash that killed the Kotlin version. By making `wzp-native` its own cdylib and `dlopen`-ing it at runtime, Bionic's `libc.so` resolves every symbol at load time the way it's supposed to, and no private TCB symbols leak.
+
+### 2. `crate-type = ["cdylib", "rlib"]` only (no `staticlib`)
+
+Same reason. The `rlib` output is needed so the `wzp-desktop` binary target can link against the library; `cdylib` is needed for Android's `System.loadLibrary`; `staticlib` would reintroduce the symbol-leak bug.
+
+### 3. Oboe audio config
+
+`Usage::VoiceCommunication` + Java-side `MODE_IN_COMMUNICATION`. **Never** call `setAudioApi(AAudio)` explicitly — on some devices (Nothing Phone in particular) it causes Oboe to open the wrong stream type and audio goes silent. Let Oboe pick the audio API automatically. This is documented in the auto-memory `project_tauri_android_audio.md`.
+
+### 4. Speaker/earpiece toggle uses `tokio::task::spawn_blocking`
+
+Oboe's `stop()` + `start()` cycle is synchronous and can block for 50–200 ms. Calling it on the tokio executor stalls every other async task (including the QUIC datagram loop), dropping audio packets. Wrapping the toggle in `spawn_blocking` isolates it to a dedicated thread pool. Fixed in commit `76a4c53`.
+
+## Build pipeline
+
+Docker on SepehrHomeserverdk, same pattern as the Android legacy pipeline and the Windows pipeline:
+
+```
+./scripts/build-tauri-android.sh         # Full: pull + build + ntfy + rustypaste
+./scripts/build-tauri-android.sh --pull  # Explicit git pull (default)
+./scripts/build-tauri-android.sh --clean # Blow away the Rust target cache
+```
+
+**Image**: `wzp-android-builder` (shared with the legacy Kotlin pipeline). The Dockerfile was extended to install Node.js 20 LTS, Android API level 36, build-tools 35.0.0, tauri-cli 2.x, and all four Android Rust targets on top of the legacy NDK 26.1 + cargo-ndk + Gradle setup. Both pipelines coexist in the same image.
+
+**Output**: `wzp-release.apk` uploaded to rustypaste, URL delivered via `ntfy.sh/wzp`.
+
+## Known quirks (Tauri Mobile specific)
+
+1. **tauri-cli `android init` writes absolute paths** into `gradle.properties` for the NDK path. Those paths are local to wherever `android init` was run, so they break any cross-machine build unless overridden with `ANDROID_NDK_HOME` at build time. The build script exports `ANDROID_NDK_HOME` explicitly to work around this.
+
+2. **API 36 vs API 34 coexistence**: the legacy Kotlin pipeline targets API 34, Tauri Mobile 2.x wants compileSdk 36. The shared Docker image installs both SDK levels so neither pipeline needs to reinstall.
+
+3. **Identity seed lives in Android-specific app data dir**: `/data/data/com.wzp.phone/files/.wzp/identity` instead of `$HOME/.wzp/identity`. The shared `load_or_create_seed()` function in `desktop/src-tauri/src/lib.rs` uses Tauri's `app_data_dir()` which resolves correctly on both Android and desktop — no per-platform code needed.
+
+4. **Direct calls on macOS previously hit an identity mismatch bug** — the `CallEngine` was using `$HOME/.wzp/identity` directly while `register_signal` used Tauri's `app_data_dir()`. Fixed by routing both through `load_or_create_seed()` (commit `2fd9465`). This was important for cross-platform consistency.
+
+## Current state (snapshot)
+
+What works:
+
+- Tauri Mobile scaffold builds and runs on Android
+- Signal hub connect + register works
+- Room mode (SFU group calls) works with Oboe audio
+- Direct 1:1 calls work with full parity to desktop
+- Speaker/earpiece toggle works without stalling the audio pipeline
+- Call history, recent contacts, deregister UI all present (inherited from desktop)
+
+What remains (task list refs in parens):
+
+- Background service for keeping signal alive when app is backgrounded (#19)
+- Proper permission requests (microphone, notifications) on first launch (#19)
+- Incoming call notification while backgrounded (#19)
+- App icon + splash screen (#19)
+
+## Testing
+
+- **Build**: `./scripts/build-tauri-android.sh` — verify the APK lands on rustypaste and installs on device.
+- **Smoke test**: Install → open app → Register → Place call → Receive call. No crashes, audio flows both ways.
+- **Speaker toggle**: During a call, toggle speaker/earpiece several times in rapid succession. Audio should never stop, and the toggle should respond within ~200 ms.
+- **Stress test**: Call for 10+ minutes continuous. No memory growth, no packet loss beyond what's attributable to the network.
+
+## Files of interest
+
+| Path | Purpose |
+|---|---|
+| `desktop/src-tauri/src/lib.rs` | Shared Tauri commands (desktop + Android) |
+| `desktop/src-tauri/src/android_audio.rs` | JVM-side speaker/earpiece routing |
+| `desktop/src-tauri/src/wzp_native.rs` | Runtime dlopen of libwzp_native.so |
+| `crates/wzp-native/` | Standalone C++/Oboe cdylib, loaded at runtime |
+| `scripts/build-tauri-android.sh` | Remote Docker build pipeline |
+| `scripts/Dockerfile.android-builder` | Shared Android Docker image (legacy + Tauri) |
+| `docs/incident-tauri-android-init-tcb.md` | Postmortem of the Kotlin+JNI crash cascade |

docs/DESIGN.md

@@ -1,168 +1,591 @@
-# WarzonePhone Detailed Design Decisions
+# WarzonePhone Design Document
 
-## Why Opus + Codec2 (Not Just One)
+> Custom encrypted VoIP protocol built in Rust. Designed for hostile network conditions: 5-70% packet loss, 100-500 kbps throughput, 300-800 ms RTT. Multi-platform: Desktop (Tauri), Android, CLI, Web.
 
-The dual-codec architecture is driven by the extreme range of network conditions WarzonePhone targets:
+## System Overview
 
-**Opus** (24/16/6 kbps) is the clear choice for normal to degraded conditions. It offers excellent quality at moderate bitrates, has built-in inband FEC and DTX (discontinuous transmission), and the `audiopus` crate provides mature Rust bindings to libopus. Opus operates at 48 kHz natively.
+WarzonePhone is a voice-over-IP system built from scratch in Rust, targeting reliable encrypted voice communication over severely degraded networks. The protocol uses adaptive codecs (Opus + Codec2), fountain-code FEC (RaptorQ), and end-to-end ChaCha20-Poly1305 encryption over a QUIC transport layer.
 
-**Codec2** (3200/1200 bps) is a narrowband vocoder designed specifically for HF radio links with extreme bandwidth constraints. At 1200 bps (1.2 kbps), it produces intelligible speech in only 6 bytes per 40ms frame -- roughly 20x lower bitrate than Opus at its minimum. The pure-Rust `codec2` crate means no C dependencies for this codec. Codec2 operates at 8 kHz, so the adaptive layer handles 48 kHz <-> 8 kHz resampling transparently.
+The system comprises three categories of components:
 
-The `AdaptiveEncoder`/`AdaptiveDecoder` in `crates/wzp-codec/src/adaptive.rs` hold both codec instances and switch between them based on the active `QualityProfile`. This avoids codec re-initialization latency during tier transitions.
+1. **Protocol crates** -- a Rust workspace of 7 library crates with a star dependency graph enabling parallel development
+2. **Client applications** -- Desktop (Tauri), Android (Kotlin + JNI), CLI, and Web (browser bridge)
+3. **Relay infrastructure** -- SFU relay daemons with federation, health probing, and Prometheus metrics
 
-**Bandwidth comparison with FEC overhead:**
+### Design Principles
 
-| Tier | Codec Bitrate | FEC Ratio | Total Bandwidth |
-|------|--------------|-----------|----------------|
-| GOOD | 24 kbps | 20% | ~28.8 kbps |
-| DEGRADED | 6 kbps | 50% | ~9.0 kbps |
-| CATASTROPHIC | 1.2 kbps | 100% | ~2.4 kbps |
+- **User sovereignty** -- client-driven route selection, BIP39 identity backup, no central authority
+- **End-to-end encryption** -- relays never see plaintext audio; SFU forwarding preserves E2E encryption
+- **Adaptive resilience** -- automatic codec and FEC switching based on observed network quality
+- **Parallel development** -- star dependency graph allows 5 agents/developers to work simultaneously with zero merge conflicts
 
-At the catastrophic tier, the entire call (audio + FEC + headers) fits within approximately 3 kbps, which is viable even over severely degraded links.
+## Architecture
 
-## Why RaptorQ Over Reed-Solomon
+### Crate Overview
 
-**Reed-Solomon** is a classical block erasure code. It works well but has fixed-rate overhead: you must decide in advance how many repair symbols to generate, and decoding requires receiving exactly K of any K+R symbols.
+The workspace contains 7 core crates plus integration binaries:
 
-**RaptorQ** (RFC 6330) is a fountain code with several advantages for VoIP:
+| Crate | Purpose | Key Dependencies |
+|-------|---------|-----------------|
+| `wzp-proto` | Protocol types, traits, wire format | serde, bytes |
+| `wzp-codec` | Audio codecs (Opus, Codec2, RNNoise) | audiopus, codec2, nnnoiseless |
+| `wzp-fec` | Forward error correction | raptorq |
+| `wzp-crypto` | Cryptography and identity | ed25519-dalek, x25519-dalek, chacha20poly1305, bip39 |
+| `wzp-transport` | QUIC transport layer | quinn, rustls |
+| `wzp-relay` | Relay daemon (SFU, federation, metrics) | tokio, prometheus |
+| `wzp-client` | Call engine and CLI | All above |
 
-1. **Rateless**: You can generate an arbitrary number of repair symbols on the fly. If conditions worsen mid-block, you can generate additional repair without re-encoding.
+Additional integration targets: `wzp-web` (browser bridge via WebSocket), Android native library (JNI), Desktop (Tauri).
 
-2. **Efficient decoding**: RaptorQ can decode from any K symbols with high probability (typically K + 1 or K + 2 suffice), compared to Reed-Solomon which requires exactly K.
+### Dependency Graph
 
-3. **Lower computational complexity**: O(K) encoding and decoding time, compared to O(K^2) for Reed-Solomon. This matters for real-time audio at 50 frames/second.
+```mermaid
+graph TD
+    PROTO["wzp-proto<br/>(Types, Traits, Wire Format)"]
 
-4. **Variable block sizes**: The encoder handles 1-56403 source symbols per block (the WZP implementation uses 5-10, but the flexibility is there).
+    CODEC["wzp-codec<br/>(Opus + Codec2 + RNNoise)"]
+    FEC["wzp-fec<br/>(RaptorQ FEC)"]
+    CRYPTO["wzp-crypto<br/>(ChaCha20 + Identity)"]
+    TRANSPORT["wzp-transport<br/>(QUIC / Quinn)"]
 
-The `raptorq` crate (v2) provides a well-tested pure-Rust implementation. The WZP FEC layer adds length-prefixed padding (2-byte LE prefix + zero-pad to 256 bytes) so that variable-length audio frames can be recovered exactly.
+    RELAY["wzp-relay<br/>(Relay Daemon)"]
+    CLIENT["wzp-client<br/>(CLI + Call Engine)"]
+    WEB["wzp-web<br/>(Browser Bridge)"]
+    DESKTOP["Desktop<br/>(Tauri + CPAL)"]
+    ANDROID["Android<br/>(Kotlin + JNI)"]
 
-**FEC bandwidth math at different loss rates:**
+    PROTO --> CODEC
+    PROTO --> FEC
+    PROTO --> CRYPTO
+    PROTO --> TRANSPORT
+
+    CODEC --> CLIENT
+    FEC --> CLIENT
+    CRYPTO --> CLIENT
+    TRANSPORT --> CLIENT
+
+    CODEC --> RELAY
+    FEC --> RELAY
+    CRYPTO --> RELAY
+    TRANSPORT --> RELAY
+
+    CLIENT --> WEB
+    CLIENT --> DESKTOP
+    CLIENT --> ANDROID
+    TRANSPORT --> WEB
+
+    FC["warzone-protocol<br/>(featherChat Identity)"] -.->|path dep| CRYPTO
+
+    style PROTO fill:#6c5ce7,color:#fff
+    style RELAY fill:#ff9f43,color:#fff
+    style CLIENT fill:#00b894,color:#fff
+    style WEB fill:#0984e3,color:#fff
+    style DESKTOP fill:#0984e3,color:#fff
+    style ANDROID fill:#0984e3,color:#fff
+    style FC fill:#fd79a8,color:#fff
+```
+
+The star pattern ensures each leaf crate (`wzp-codec`, `wzp-fec`, `wzp-crypto`, `wzp-transport`) depends only on `wzp-proto` and never on each other. This enables:
+
+- **Parallel development** -- 5 agents work on 5 crates with no merge conflicts
+- **Independent testing** -- each crate has self-contained tests
+- **Pluggability** -- any implementation can be swapped by implementing the same trait
+- **Fast compilation** -- changing one leaf only recompiles that leaf and integration crates
+
+## Audio Pipeline
+
+### Encode Pipeline (Mic to Network)
+
+```mermaid
+sequenceDiagram
+    participant Mic as Microphone
+    participant RNN as RNNoise Denoise
+    participant VAD as Silence Detector
+    participant ENC as Opus/Codec2 Encode
+    participant FEC as RaptorQ FEC Encode
+    participant INT as Interleaver
+    participant HDR as Header Assembly
+    participant CRYPT as ChaCha20-Poly1305
+    participant QUIC as QUIC Datagram
+
+    Mic->>RNN: PCM i16 x 960 (20ms @ 48kHz)
+    RNN->>VAD: Denoised samples (2 x 480)
+    alt Silence detected (>100ms)
+        VAD->>ENC: ComfortNoise packet (every 200ms)
+    else Active speech or hangover
+        VAD->>ENC: Active audio frame
+    end
+    ENC->>FEC: Compressed frame (padded to 256 bytes)
+    FEC->>FEC: Accumulate block (5-10 frames)
+    FEC->>INT: Source + repair symbols
+    INT->>HDR: Interleaved packets (depth=3)
+    HDR->>CRYPT: MediaHeader (12B) or MiniHeader (4B)
+    CRYPT->>QUIC: Header=AAD, Payload=encrypted
+```
+
+### Decode Pipeline (Network to Speaker)
+
+```mermaid
+sequenceDiagram
+    participant QUIC as QUIC Datagram
+    participant CRYPT as ChaCha20-Poly1305
+    participant HDR as Header Parse
+    participant DEINT as De-interleaver
+    participant FEC as RaptorQ FEC Decode
+    participant JIT as Jitter Buffer
+    participant DEC as Opus/Codec2 Decode
+    participant SPK as Speaker
+
+    QUIC->>CRYPT: Encrypted packet
+    CRYPT->>HDR: Decrypt (header=AAD)
+    HDR->>DEINT: Parsed MediaHeader + payload
+    DEINT->>FEC: Reordered symbols
+    FEC->>FEC: Reconstruct from any K of K+R symbols
+    FEC->>JIT: Recovered audio frames
+    JIT->>JIT: Sequence-ordered BTreeMap
+    JIT->>DEC: Pop when depth >= target
+    DEC->>SPK: PCM i16 x 960
+```
+
+## Codec System
+
+WarzonePhone uses a dual-codec architecture to cover the full range of network conditions:
+
+### Opus (Primary)
+
+Opus is the primary codec for normal to degraded conditions. It operates at 48 kHz natively with built-in inband FEC and DTX (discontinuous transmission). The `audiopus` crate provides mature Rust bindings to libopus.
+
+| Profile | Bitrate | Frame Duration | FEC Ratio | Total Bandwidth | Use Case |
+|---------|---------|---------------|-----------|----------------|----------|
+| Studio 64k | 64 kbps | 20ms | 10% | 70.4 kbps | LAN, excellent WiFi |
+| Studio 48k | 48 kbps | 20ms | 10% | 52.8 kbps | Good WiFi, wired |
+| Studio 32k | 32 kbps | 20ms | 10% | 35.2 kbps | WiFi, LTE |
+| Good (24k) | 24 kbps | 20ms | 20% | 28.8 kbps | WiFi, LTE, decent links |
+| Opus 16k | 16 kbps | 20ms | 20% | 19.2 kbps | 3G, moderate congestion |
+| Degraded (6k) | 6 kbps | 40ms | 50% | 9.0 kbps | 3G, congested WiFi |
+
+### Codec2 (Fallback)
+
+Codec2 is a narrowband vocoder designed for HF radio links with extreme bandwidth constraints. It operates at 8 kHz, and the adaptive layer handles 48 kHz <-> 8 kHz resampling transparently. The pure-Rust `codec2` crate means no C dependencies.
+
+| Profile | Bitrate | Frame Duration | FEC Ratio | Total Bandwidth | Use Case |
+|---------|---------|---------------|-----------|----------------|----------|
+| Codec2 3200 | 3.2 kbps | 20ms | 50% | 4.8 kbps | Poor conditions |
+| Catastrophic (1200) | 1.2 kbps | 40ms | 100% | 2.4 kbps | Satellite, extreme loss |
+
+### ComfortNoise
+
+When the silence detector identifies no speech activity for over 100ms, the encoder switches to emitting a ComfortNoise packet every 200ms instead of encoding silence. This provides approximately 50% bandwidth savings in typical conversations.
+
+### Adaptive Switching
+
+The `AdaptiveEncoder`/`AdaptiveDecoder` in `wzp-codec` hold both codec instances and switch between them based on the active `QualityProfile`. This avoids codec re-initialization latency during tier transitions. The `AdaptiveQualityController` in `wzp-proto` manages tier transitions with hysteresis:
+
+- **Downgrade**: 3 consecutive bad reports (2 on cellular networks)
+- **Upgrade**: 10 consecutive good reports (one tier at a time)
+- **Network handoff**: WiFi-to-cellular switch triggers preemptive one-tier downgrade plus a temporary 10-second FEC boost (+20%)
+
+Quality tier classification thresholds:
+
+| Tier | WiFi/Unknown | Cellular |
+|------|-------------|----------|
+| Good | loss < 10%, RTT < 400ms | loss < 8%, RTT < 300ms |
+| Degraded | loss 10-40%, RTT 400-600ms | loss 8-25%, RTT 300-500ms |
+| Catastrophic | loss > 40%, RTT > 600ms | loss > 25%, RTT > 500ms |
+
+## Forward Error Correction (FEC)
+
+### Why RaptorQ Over Reed-Solomon
+
+WarzonePhone uses RaptorQ (RFC 6330) fountain codes via the `raptorq` crate:
+
+1. **Rateless** -- generate arbitrary repair symbols on the fly; if conditions worsen mid-block, generate additional repair without re-encoding
+2. **Efficient decoding** -- decode from any K symbols with high probability (typically K + 1 or K + 2 suffice)
+3. **Lower complexity** -- O(K) encoding/decoding time vs O(K^2) for Reed-Solomon
+4. **Variable block sizes** -- 1-56,403 source symbols per block (WZP uses 5-10)
+
+### FEC Block Structure
+
+Each FEC block consists of 5-10 audio frames padded to 256-byte symbols with a 2-byte LE length prefix:
+
+```
+[len:u16 LE][audio_frame][zero_padding_to_256_bytes]
+```
+
+### Loss Survival by FEC Ratio
 
 With 5 source frames per block:
-- 20% repair (GOOD): 1 repair symbol. Survives loss of 1 out of 6 packets (16.7% loss).
-- 50% repair (DEGRADED): 3 repair symbols. Survives loss of 3 out of 8 packets (37.5% loss).
-- 100% repair (CATASTROPHIC): 5 repair symbols. Survives loss of 5 out of 10 packets (50% loss).
 
-The benchmark (`wzp-bench --fec --loss 30`) dynamically scales the FEC ratio to survive the requested loss percentage.
+| FEC Ratio | Repair Symbols | Survives Loss | Profile |
+|-----------|---------------|---------------|---------|
+| 10% | 1 | 1 of 6 (16.7%) | Studio |
+| 20% | 1 | 1 of 6 (16.7%) | Good |
+| 50% | 3 | 3 of 8 (37.5%) | Degraded |
+| 100% | 5 | 5 of 10 (50.0%) | Catastrophic |
 
-## Why QUIC Over Raw UDP
+### Interleaving
 
-Raw UDP would be simpler and lower-latency, but QUIC (via the `quinn` crate) provides:
+Burst loss protection via depth-3 interleaving: packets from 3 consecutive FEC blocks are interleaved before transmission. A burst of 3 consecutive lost packets affects 3 different blocks (1 loss each) rather than destroying 1 block entirely.
 
-1. **DATAGRAM frames**: Unreliable delivery without head-of-line blocking (RFC 9221). Media packets use this path, so they behave like UDP datagrams but benefit from QUIC's connection management.
+```mermaid
+graph LR
+    subgraph "FEC Encoder"
+        F1[Frame 1] --> BLK[Source Block<br/>5-10 frames]
+        F2[Frame 2] --> BLK
+        F3[Frame 3] --> BLK
+        F4[Frame 4] --> BLK
+        F5[Frame 5] --> BLK
+        BLK --> SRC[Source Symbols]
+        BLK --> REP[Repair Symbols<br/>ratio-dependent]
+        SRC --> INT[Interleaver<br/>depth=3]
+        REP --> INT
+    end
 
-2. **Reliable streams**: Signaling messages (CallOffer, CallAnswer, Rekey, Hangup) require reliable delivery. QUIC provides multiplexed streams without needing a separate TCP connection.
+    subgraph "Network"
+        INT --> LOSS{Packet Loss}
+        LOSS -->|some lost| RCV[Received Symbols]
+    end
 
-3. **Built-in congestion control**: QUIC's congestion control prevents overwhelming degraded links, which is important when chaining relays.
+    subgraph "FEC Decoder"
+        RCV --> DEINT[De-interleaver]
+        DEINT --> RAPTORQ[RaptorQ Decode<br/>Any K of K+R]
+        RAPTORQ --> OUT[Original Frames]
+    end
 
-4. **Connection migration**: QUIC connections survive IP address changes (e.g., WiFi to cellular handoff), which is valuable for mobile clients.
-
-5. **TLS 1.3 built-in**: The QUIC handshake provides encryption at the transport level. While WZP has its own end-to-end ChaCha20 layer, the QUIC TLS protects the header and signaling from eavesdroppers.
-
-6. **NAT keepalive**: QUIC's built-in keep-alive (configured at 5-second intervals) maintains NAT bindings without application-level pings.
-
-7. **Firewall traversal**: QUIC runs on UDP port 443 by default, which is commonly allowed through firewalls. The `wzp` ALPN protocol identifier distinguishes WZP traffic.
-
-The tradeoff is approximately 20-40 bytes of additional per-packet overhead compared to raw UDP (QUIC short header + DATAGRAM frame overhead).
-
-## Why ChaCha20-Poly1305 Over AES-GCM
-
-1. **Software performance**: ChaCha20-Poly1305 is faster than AES-GCM on hardware without AES-NI instructions. This matters for ARM devices (Android phones, Raspberry Pi relays, embedded systems) where AES hardware acceleration may be absent.
-
-2. **Constant-time by design**: ChaCha20 uses only add-rotate-XOR operations, making it inherently resistant to timing side-channel attacks. AES-GCM implementations without hardware support often require careful constant-time implementation.
-
-3. **Warzone messenger compatibility**: The existing Warzone messenger uses ChaCha20-Poly1305 for message encryption. Reusing the same primitive simplifies the security audit and allows key material to be shared across messaging and calling.
-
-4. **16-byte overhead**: Both ChaCha20-Poly1305 and AES-128-GCM produce a 16-byte authentication tag. There is no size advantage to AES-GCM.
-
-5. **AEAD with AAD**: The MediaHeader is used as Associated Authenticated Data (AAD), ensuring the header is authenticated but not encrypted. This allows relays to read routing information (block ID, sequence number) without decrypting the payload.
-
-## Why Star Dependency Graph (Parallel Development)
-
-The workspace follows a strict star dependency pattern:
-
-```
-         wzp-proto (hub)
-        /    |    \    \
-  wzp-codec  wzp-fec  wzp-crypto  wzp-transport
-        \    |    /    /
-         wzp-relay
-         wzp-client
-         wzp-web
+    style LOSS fill:#e17055,color:#fff
+    style RAPTORQ fill:#00b894,color:#fff
 ```
 
-- `wzp-proto` defines all trait interfaces and wire format types
-- Each "leaf" crate (codec, fec, crypto, transport) depends only on `wzp-proto`
-- No leaf crate depends on another leaf crate
-- Integration crates (relay, client, web) depend on all leaves
+## Transport Layer
 
-This enables:
-1. **Parallel development**: 5 agents/developers can work on 5 crates simultaneously with zero merge conflicts
-2. **Independent testing**: Each crate has comprehensive tests that run without requiring other implementations
-3. **Pluggability**: Any implementation can be swapped (e.g., replace RaptorQ with Reed-Solomon) by implementing the same trait
-4. **Fast compilation**: Changes to one leaf only recompile that leaf and the integration crates, not other leaves
+### Why QUIC Over Raw UDP
 
-## Jitter Buffer Trade-offs
+WarzonePhone uses QUIC (via the `quinn` crate) rather than raw UDP for several reasons:
 
-The jitter buffer must balance two competing goals:
+| Feature | Benefit |
+|---------|---------|
+| DATAGRAM frames (RFC 9221) | Unreliable delivery without head-of-line blocking -- behaves like UDP for media |
+| Reliable streams | Multiplexed signaling (CallOffer, Hangup, Rekey) without a separate TCP connection |
+| Congestion control | Prevents overwhelming degraded links, important when chaining relays |
+| Connection migration | Connections survive IP address changes (WiFi to cellular handoff) |
+| TLS 1.3 built-in | Transport-level encryption protects headers and signaling |
+| NAT keepalive | 5-second interval maintains NAT bindings without application-level pings |
+| Firewall traversal | Runs on UDP port 443 with `wzp` ALPN identifier |
 
-**Lower latency** (smaller buffer):
-- Better conversational interactivity
-- Less memory usage
-- But more vulnerable to jitter and reordering
+The tradeoff is approximately 20-40 bytes of additional per-packet overhead compared to raw UDP.
 
-**Higher quality** (larger buffer):
-- More time to receive out-of-order packets
-- More time for FEC recovery (repair packets may arrive after source packets)
-- But adds perceptible delay to the conversation
+### Wire Formats
 
-The default configuration:
-- Target: 10 packets (200ms) for the client, 50 packets (1s) for the relay
-- Minimum: 3 packets (60ms) before playout begins (client), 25 packets (500ms) for relay
-- Maximum: 250 packets (5s) absolute cap
+#### MediaHeader (12 bytes)
 
-The relay uses a deeper buffer because it needs to absorb jitter from the lossy inter-relay link. The client uses a shallower buffer for lower latency since it is on the last hop.
+```
+Byte 0:  [V:1][T:1][CodecID:4][Q:1][FecRatioHi:1]
+Byte 1:  [FecRatioLo:6][unused:2]
+Bytes 2-3: sequence (u16 BE)
+Bytes 4-7: timestamp_ms (u32 BE)
+Byte 8:   fec_block_id (u8)
+Byte 9:   fec_symbol_idx (u8)
+Byte 10:  reserved
+Byte 11:  csrc_count
 
-**Known issue**: The current jitter buffer does not adapt its depth based on observed jitter. It uses sequence-number ordering only, without timestamp-based playout scheduling. This can lead to drift during long calls, as observed in echo tests.
+V = version (0), T = is_repair, CodecID = codec, Q = quality_report appended
+```
 
-## Browser Audio: AudioWorklet vs ScriptProcessorNode
+#### MiniHeader (4 bytes, compressed)
 
-The web bridge (`crates/wzp-web/static/`) uses AudioWorklet as the primary audio I/O mechanism, with ScriptProcessorNode as a fallback.
+```
+Bytes 0-1: timestamp_delta_ms (u16 BE)
+Bytes 2-3: payload_len (u16 BE)
 
-**AudioWorklet** (preferred):
-- Runs on a dedicated audio rendering thread
-- Lower latency (no main-thread round-trip)
-- Consistent 128-sample callback timing
-- Supported in Chrome 66+, Firefox 76+, Safari 14.1+
+Preceded by FRAME_TYPE_MINI (0x01). Full header every 50 frames (~1s).
+Saves 8 bytes/packet (67% header reduction).
+```
 
-**ScriptProcessorNode** (fallback):
-- Runs on the main thread via `onaudioprocess` callback
-- Higher latency, potential glitches from main-thread GC pauses
-- Deprecated by the Web Audio specification
-- Used when AudioWorklet is not available
+#### TrunkFrame (batched datagrams)
 
-Both paths accumulate Float32 samples into 960-sample (20ms) Int16 frames before sending via WebSocket, matching the WZP codec frame size.
+```
+[count:u16]
+  [session_id:2][len:u16][payload:len]  x count
 
-**Playback** uses an AudioWorklet with a ring buffer capped at 200ms (9600 samples at 48 kHz). When the buffer exceeds this limit, old samples are dropped to prevent unbounded drift. The fallback path uses scheduled `AudioBufferSourceNode` instances.
+Packs multiple session packets into one QUIC datagram.
+Max 10 entries or 1200 bytes, flushed every 5ms.
+```
 
-## Room Mode: SFU vs MCU Trade-offs
+#### QualityReport (4 bytes, optional trailer)
 
-WarzonePhone implements an **SFU** (Selective Forwarding Unit) architecture:
+```
+Byte 0: loss_pct (0-255 maps to 0-100%)
+Byte 1: rtt_4ms (0-255 maps to 0-1020ms)
+Byte 2: jitter_ms
+Byte 3: bitrate_cap_kbps
+```
 
-**SFU** (implemented):
-- Relay forwards each participant's packets to all other participants unchanged
-- No transcoding -- the relay never decodes or re-encodes audio
-- O(N) bandwidth at the relay for N participants (each packet is sent N-1 times)
-- Each client receives separate streams from each other participant
-- Client must mix/decode multiple streams locally
-- Lower relay CPU usage (no transcoding)
-- End-to-end encryption is preserved (relay never sees plaintext)
+### Bandwidth Summary
 
-**MCU** (not implemented, for comparison):
-- Relay would decode all streams, mix them, and re-encode a single combined stream
-- O(1) bandwidth to each client (receives one mixed stream)
-- Requires the relay to have codec keys (breaks E2E encryption)
-- Higher relay CPU (decoding N streams + mixing + re-encoding)
-- Audio quality loss from re-encoding
+| Profile | Audio | FEC Overhead | Total | Silence Savings |
+|---------|-------|-------------|-------|----------------|
+| Studio 64k | 64 kbps | 10% = 6.4 kbps | **70.4 kbps** | ~50% with DTX |
+| Studio 48k | 48 kbps | 10% = 4.8 kbps | **52.8 kbps** | ~50% with DTX |
+| Studio 32k | 32 kbps | 10% = 3.2 kbps | **35.2 kbps** | ~50% with DTX |
+| Good (24k) | 24 kbps | 20% = 4.8 kbps | **28.8 kbps** | ~50% with DTX |
+| Degraded (6k) | 6 kbps | 50% = 3.0 kbps | **9.0 kbps** | ~50% with DTX |
+| Catastrophic (1.2k) | 1.2 kbps | 100% = 1.2 kbps | **2.4 kbps** | ~50% with DTX |
 
-The SFU choice is driven by the E2E encryption requirement: since relays never have access to the audio codec keys, they cannot decode, mix, or re-encode. The current room implementation in `crates/wzp-relay/src/room.rs` forwards received datagrams to all other participants in the room with best-effort delivery -- if one send fails, the relay continues to the next participant.
+Additional savings: MiniHeaders save 8 bytes/packet (67% header reduction). Trunking shares QUIC overhead across multiplexed sessions.
+
+## Security
+
+### Identity Model
+
+Every user has a persistent identity derived from a 32-byte seed:
+
+```mermaid
+graph TD
+    SEED["32-byte Seed<br/>(BIP39 Mnemonic: 24 words)"] --> HKDF1["HKDF<br/>info='warzone-ed25519'"]
+    SEED --> HKDF2["HKDF<br/>info='warzone-x25519'"]
+
+    HKDF1 --> ED["Ed25519 SigningKey<br/>(Digital Signatures)"]
+    HKDF2 --> X25519["X25519 StaticSecret<br/>(Key Agreement)"]
+
+    ED --> VKEY["Ed25519 VerifyingKey<br/>(Public)"]
+    X25519 --> XPUB["X25519 PublicKey<br/>(Public)"]
+
+    VKEY --> FP["Fingerprint<br/>SHA-256(pubkey), truncated 16 bytes<br/>xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx"]
+
+    style SEED fill:#6c5ce7,color:#fff
+    style FP fill:#fd79a8,color:#fff
+    style ED fill:#ee5a24,color:#fff
+    style X25519 fill:#00b894,color:#fff
+```
+
+**BIP39 Mnemonic Backup**: The 32-byte seed can be encoded as a 24-word BIP39 mnemonic for human-readable backup. The same seed produces the same identity on any platform.
+
+**featherChat Compatibility**: The identity derivation is compatible with the Warzone messenger (featherChat), allowing a shared identity across messaging and calling.
+
+### Cryptographic Handshake
+
+```mermaid
+sequenceDiagram
+    participant C as Caller
+    participant R as Relay / Callee
+
+    Note over C: Derive identity from seed<br/>Ed25519 + X25519 via HKDF
+
+    C->>C: Generate ephemeral X25519 keypair
+    C->>C: Sign(ephemeral_pub || "call-offer")
+    C->>R: CallOffer { identity_pub, ephemeral_pub, signature, profiles }
+
+    R->>R: Verify Ed25519 signature
+    R->>R: Generate ephemeral X25519 keypair
+    R->>R: shared_secret = DH(eph_b, eph_a)
+    R->>R: session_key = HKDF(shared_secret, "warzone-session-key")
+    R->>R: Sign(ephemeral_pub || "call-answer")
+    R->>C: CallAnswer { identity_pub, ephemeral_pub, signature, profile }
+
+    C->>C: Verify signature
+    C->>C: shared_secret = DH(eph_a, eph_b)
+    C->>C: session_key = HKDF(shared_secret)
+
+    Note over C,R: Both have identical ChaCha20-Poly1305 session key
+    C->>R: Encrypted media (QUIC datagrams)
+    R->>C: Encrypted media (QUIC datagrams)
+
+    Note over C,R: Rekey every 65,536 packets<br/>New ephemeral DH + HKDF mix
+```
+
+### Encryption Details
+
+| Component | Algorithm | Purpose |
+|-----------|-----------|---------|
+| Identity signing | Ed25519 | Authenticate handshake messages |
+| Key agreement | X25519 (ephemeral) | Derive shared secret |
+| Key derivation | HKDF-SHA256 | Derive session key from shared secret |
+| Media encryption | ChaCha20-Poly1305 | Encrypt audio payloads (16-byte tag) |
+| Nonce construction | Deterministic from sequence number | No nonce reuse, no state sync needed |
+| Anti-replay | Sliding window (64-packet) | Reject duplicate/old packets |
+| Forward secrecy | Rekey every 65,536 packets | New ephemeral DH + HKDF mix |
+
+**Why ChaCha20-Poly1305 over AES-GCM**:
+- Faster on hardware without AES-NI (ARM phones, Raspberry Pi relays)
+- Inherently constant-time (add-rotate-XOR only)
+- Compatible with Warzone messenger (featherChat)
+- Same 16-byte authentication tag overhead as AES-GCM
+
+**AEAD with AAD**: The MediaHeader is used as Associated Authenticated Data. The header is authenticated but not encrypted, allowing relays to read routing information (block ID, sequence number) without decrypting the payload.
+
+### Trust on First Use (TOFU)
+
+Clients remember the relay's TLS certificate fingerprint after first connection. If the fingerprint changes on a subsequent connection, the desktop client shows a "Server Key Changed" warning dialog. The relay derives its TLS certificate deterministically from its persisted identity seed, so the fingerprint is stable across restarts.
+
+## Relay Architecture
+
+### Room Mode (Default SFU)
+
+In room mode, the relay acts as a Selective Forwarding Unit. Clients join named rooms via the QUIC SNI (Server Name Indication) field. The relay forwards each participant's encrypted packets to all other participants in the room without decoding or re-encoding.
+
+```mermaid
+graph TB
+    subgraph "Room Mode (SFU)"
+        C1[Client 1] -->|"QUIC SNI=room-hash"| RM[Room Manager]
+        C2[Client 2] -->|"QUIC SNI=room-hash"| RM
+        C3[Client 3] -->|"QUIC SNI=room-hash"| RM
+        RM --> R1[Room 'podcast']
+        R1 -->|fan-out| C1
+        R1 -->|fan-out| C2
+        R1 -->|fan-out| C3
+    end
+
+    style RM fill:#ff9f43,color:#fff
+    style R1 fill:#fdcb6e
+```
+
+**SFU vs MCU trade-off**: SFU was chosen because it preserves end-to-end encryption (the relay never sees plaintext audio). An MCU would need to decode, mix, and re-encode, breaking E2E encryption. The trade-off is O(N) bandwidth at the relay for N participants.
+
+### Forward Mode
+
+With `--remote`, the relay forwards all traffic to a remote relay. Used for chaining relays across lossy or censored links:
+
+```
+Client --> Relay A (--remote B) --> Relay B --> Destination Client
+```
+
+The relay pipeline in forward mode: FEC decode, jitter buffer, then FEC re-encode for the next hop.
+
+## Federation
+
+### Overview
+
+Two or more relays form a federation mesh. Each relay is an independent SFU. When configured to trust each other, they bridge **global rooms** -- participants on relay A in a global room hear participants on relay B in the same room.
+
+### Configuration
+
+Federation uses three TOML configuration sections:
+
+- `[[peers]]` -- outbound connections to peer relays (url + TLS fingerprint)
+- `[[trusted]]` -- inbound connections accepted from relays (TLS fingerprint only)
+- `[[global_rooms]]` -- room names to bridge across all federated peers
+
+### Federation Topology
+
+```mermaid
+graph TB
+    subgraph "Relay A (EU)"
+        A_RM[Room Manager]
+        A_FM[Federation Manager]
+        A1[Alice - local]
+        A2[Bob - local]
+        A_RM --> A_FM
+    end
+
+    subgraph "Relay B (US)"
+        B_RM[Room Manager]
+        B_FM[Federation Manager]
+        B1[Charlie - local]
+        B_RM --> B_FM
+    end
+
+    A_FM <-->|"QUIC SNI='_federation'<br/>GlobalRoomActive/Inactive<br/>Media forwarding"| B_FM
+
+    A1 -->|media| A_RM
+    A2 -->|media| A_RM
+    B1 -->|media| B_RM
+
+    A_RM -->|"federated fan-out"| A1
+    A_RM -->|"federated fan-out"| A2
+    B_RM -->|"federated fan-out"| B1
+
+    style A_FM fill:#6c5ce7,color:#fff
+    style B_FM fill:#6c5ce7,color:#fff
+    style A_RM fill:#ff9f43,color:#fff
+    style B_RM fill:#ff9f43,color:#fff
+```
+
+### Protocol
+
+1. On startup, each relay connects to all configured `[[peers]]` via QUIC with SNI `"_federation"`
+2. After QUIC handshake, sends `FederationHello { tls_fingerprint }` for identity verification
+3. Peer verifies the fingerprint against its `[[trusted]]` or `[[peers]]` list
+4. When a local participant joins a global room, sends `GlobalRoomActive { room }` to all peers
+5. When the last local participant leaves, sends `GlobalRoomInactive { room }`
+6. Media is forwarded as `[room_hash:8][original_media_packet]` -- the relay does not decrypt
+
+### What Relays Do NOT Do
+
+- **No transcoding** -- media passes through as-is
+- **No re-encryption** -- packets are already encrypted E2E
+- **No central coordinator** -- each relay independently connects to configured peers
+- **No automatic peer discovery** -- peers must be explicitly configured
+
+### Failure Handling
+
+- If a peer goes down, local rooms continue working; federated participants disappear from presence
+- Reconnection: every 30 seconds with exponential backoff up to 5 minutes
+- If a peer restarts with a different identity, the fingerprint check fails with a clear log message
+
+## Jitter Buffer
+
+The jitter buffer balances latency vs quality:
+
+| Setting | Client | Relay |
+|---------|--------|-------|
+| Target depth | 10 packets (200ms) | 50 packets (1s) |
+| Minimum before playout | 3 packets (60ms) | 25 packets (500ms) |
+| Maximum cap | 250 packets (5s) | 250 packets (5s) |
+
+The relay uses a deeper buffer to absorb jitter from lossy inter-relay links. The client uses a shallower buffer for lower latency.
+
+The adaptive playout delay tracks jitter via exponential moving average and adjusts the target depth:
+
+```
+target_delay = ceil(jitter_ema / 20ms) + 2
+```
+
+**Known limitation**: The current jitter buffer does not use timestamp-based playout scheduling. It relies on sequence-number ordering only, which can lead to drift during long calls.
+
+## Signal Messages
+
+Signal messages are sent over reliable QUIC streams as length-prefixed JSON:
+
+```
+[4-byte length prefix][serde_json payload]
+```
+
+| Message | Purpose |
+|---------|---------|
+| `CallOffer` | Identity, ephemeral key, signature, supported profiles |
+| `CallAnswer` | Identity, ephemeral key, signature, chosen profile |
+| `AuthToken` | featherChat bearer token for relay authentication |
+| `Hangup` | Reason: Normal, Busy, Declined, Timeout, Error |
+| `Hold` / `Unhold` | Call hold state |
+| `Mute` / `Unmute` | Mic mute state |
+| `Transfer` | Call transfer to another relay/fingerprint |
+| `Rekey` | New ephemeral key for forward secrecy |
+| `QualityUpdate` | Quality report + recommended profile |
+| `Ping` / `Pong` | Latency measurement (timestamp_ms) |
+| `RoomUpdate` | Participant list changes |
+| `PresenceUpdate` | Federation presence gossip |
+| `RouteQuery` / `RouteResponse` | Presence discovery for routing |
+| `FederationHello` | Relay identity during federation setup |
+| `GlobalRoomActive` / `GlobalRoomInactive` | Federation room bridging |
+
+## Test Coverage
+
+272 tests across all crates, 0 failures:
+
+| Crate | Tests | Key Coverage |
+|-------|-------|-------------|
+| wzp-proto | 41 | Wire format, jitter buffer, quality tiers, mini-frames, trunking |
+| wzp-codec | 31 | Opus/Codec2 roundtrip, silence detection, noise suppression |
+| wzp-fec | 22 | RaptorQ encode/decode, loss recovery, interleaving |
+| wzp-crypto | 34 + 28 compat | Encrypt/decrypt, handshake, anti-replay, featherChat identity |
+| wzp-transport | 2 | QUIC connection setup |
+| wzp-relay | 40 + 4 integration | Room ACL, session mgmt, metrics, probes, mesh, trunking |
+| wzp-client | 30 + 2 integration | Encoder/decoder, quality adapter, silence, drift, sweep |
+| wzp-web | 2 | Metrics |
+
+## Build Requirements
+
+- **Rust** 1.85+ (2024 edition)
+- **Linux**: cmake, pkg-config, libasound2-dev (for audio feature)
+- **macOS**: Xcode command line tools (CoreAudio included)
+- **Android**: NDK r27c, cmake 3.28+ (from pip)

docs/PRD-coordinated-codec.md

@@ -0,0 +1,198 @@
+# PRD: Coordinated Codec Switching (Relay-Judged Quality)
+
+## Problem
+
+The current adaptive quality system (`QualityAdapter` in call.rs) exists but isn't wired into either engine. Clients encode at a fixed quality chosen at call start. When network conditions change mid-call, audio degrades instead of gracefully stepping down. When conditions improve, clients stay on low quality unnecessarily.
+
+Additionally, in SFU mode with multiple participants, uncoordinated codec switching creates asymmetry: if client A upgrades to 64k while B stays on 24k, bandwidth is wasted. Participants should switch together.
+
+## Solution
+
+The **relay acts as the quality judge** since it sees both sides of every connection. It monitors packet loss, jitter, and RTT per participant, then signals quality recommendations. Clients react to these signals with coordinated codec switches.
+
+## Architecture
+
+```
+┌─────────┐        ┌─────────┐        ┌─────────┐
+│ Client A │◄──────►│  Relay  │◄──────►│ Client B │
+│          │        │ (judge) │        │          │
+│ Encoder  │        │         │        │ Encoder  │
+│ Decoder  │        │ Monitor │        │ Decoder  │
+└─────────┘        │ per-peer│        └─────────┘
+                    │ quality │
+                    └────┬────┘
+                         │
+                    Quality Signals:
+                    - StableSignal (conditions good)
+                    - DegradeSignal (conditions bad)
+                    - UpgradeProposal (try higher quality?)
+                    - UpgradeConfirm (all agreed, switch at T)
+```
+
+## Quality Classification (Relay-Side)
+
+The relay monitors each participant's connection quality:
+
+| Condition | Classification | Action |
+|-----------|---------------|--------|
+| loss >= 15% OR RTT >= 200ms | Critical | Immediate downgrade signal |
+| loss >= 5% OR RTT >= 100ms | Degraded | Downgrade signal after 3 reports |
+| loss < 2% AND RTT < 80ms | Good | Stable signal |
+| loss < 1% AND RTT < 50ms for 30s | Excellent | Upgrade proposal |
+| loss < 0.5% AND RTT < 30ms for 60s | Studio | Studio upgrade proposal |
+
+## Coordinated Switching Protocol
+
+### Downgrade (fast, safety-first)
+
+1. Relay detects degradation for ANY participant
+2. Relay sends `QualityUpdate { recommended_profile: DEGRADED }` to ALL participants
+3. ALL participants immediately switch encoder to the recommended profile
+4. No negotiation — downgrade is mandatory and instant
+
+### Upgrade (slow, consensual)
+
+1. Relay detects sustained good conditions for ALL participants (threshold: 30s stable)
+2. Relay sends `UpgradeProposal { target_profile, switch_timestamp }` to all
+3. Each client responds: `UpgradeAccept` or `UpgradeReject`
+4. If ALL accept within 5s → Relay sends `UpgradeConfirm { profile, switch_at_ms }`
+5. All clients switch encoder at the agreed timestamp (relative to session clock)
+6. If ANY rejects or times out → upgrade cancelled, stay on current profile
+
+### Asymmetric Encoding (SFU optimization)
+
+In SFU mode, each client encodes independently. The relay could allow:
+- Client A (strong connection): encode at 64k
+- Client B (weak connection): encode at 6k
+- Relay forwards A's 64k to B's decoder (auto-switch handles it)
+- B benefits from A's quality without needing to send at 64k
+
+This requires NO protocol changes — just each client independently following the relay's recommendation for their own encoding quality. The decoder already handles any codec.
+
+### Split Network Consideration
+
+If participant A has great quality but participant C has terrible quality:
+- Option 1: **Match weakest link** — everyone encodes at C's level (current approach, simple)
+- Option 2: **Per-participant recommendations** — A encodes at 64k, C encodes at 6k. B (good connection) receives and decodes both. Works because decoders auto-switch per packet.
+- Option 3: **Relay transcoding** — relay re-encodes A's 64k as 6k for C. Adds CPU on relay, but saves bandwidth for C. Future feature.
+
+Recommended: start with Option 1 (match weakest), add Option 2 later.
+
+## Signal Messages (New/Modified)
+
+```rust
+/// Quality signal from relay to client
+QualityDirective {
+    /// Recommended profile to use for encoding
+    recommended_profile: QualityProfile,
+    /// Reason for the recommendation
+    reason: QualityReason,
+}
+
+enum QualityReason {
+    /// Network conditions require this quality level
+    NetworkCondition,
+    /// Coordinated upgrade — all participants agreed
+    CoordinatedUpgrade,
+    /// Coordinated downgrade — weakest link determines level
+    CoordinatedDowngrade,
+}
+
+/// Upgrade proposal from relay
+UpgradeProposal {
+    target_profile: QualityProfile,
+    /// Milliseconds from now when the switch would happen
+    switch_delay_ms: u32,
+}
+
+/// Client response to upgrade proposal
+UpgradeResponse {
+    accepted: bool,
+}
+
+/// Confirmed upgrade — all clients switch at this time
+UpgradeConfirm {
+    profile: QualityProfile,
+    /// Session-relative timestamp to switch (ms since call start)
+    switch_at_session_ms: u64,
+}
+```
+
+## Relay-Side Implementation
+
+### Per-Participant Quality Tracking
+
+```rust
+struct ParticipantQuality {
+    /// Sliding window of recent observations
+    loss_samples: VecDeque<f32>,    // last 30 seconds
+    rtt_samples: VecDeque<u32>,     // last 30 seconds
+    jitter_samples: VecDeque<u32>,
+    /// Current classification
+    classification: QualityClass,
+    /// How long current classification has been stable
+    stable_since: Instant,
+}
+```
+
+### Quality Monitor Task (on relay)
+
+Runs alongside the SFU forwarding loop:
+1. Every 1 second, compute per-participant quality from QUIC connection stats
+2. Classify each participant
+3. If ANY participant degrades → send downgrade to ALL
+4. If ALL participants stable for threshold → propose upgrade
+5. Track upgrade negotiation state
+
+### Integration with Existing Code
+
+The relay already has access to:
+- `QuinnTransport::path_quality()` → loss, RTT, jitter, bandwidth estimates
+- `QualityReport` embedded in media packet headers
+- Per-session metrics in `RelayMetrics`
+
+The quality monitor just needs to read these existing metrics and produce signals.
+
+## Client-Side Implementation
+
+### Handling Quality Signals
+
+In the recv loop (both Android engine and desktop engine):
+```rust
+SignalMessage::QualityDirective { recommended_profile, .. } => {
+    // Immediate: switch encoder to recommended profile
+    encoder.set_profile(recommended_profile)?;
+    fec_enc = create_encoder(&recommended_profile);
+    frame_samples = frame_samples_for(&recommended_profile);
+    info!(codec = ?recommended_profile.codec, "quality directive: switched");
+}
+```
+
+### P2P Quality (simpler case)
+
+For P2P calls (no relay), both clients directly observe quality:
+1. Each client runs its own `QualityAdapter` on the direct connection
+2. When quality changes, client proposes to peer via signal
+3. Simpler negotiation: only 2 parties, no relay middleman
+4. Same coordinated switching logic, just peer-to-peer signals
+
+## Backporting P2P → Relay
+
+The quality monitoring and codec switching logic is identical:
+- **P2P**: client observes quality directly → proposes switch to peer
+- **Relay**: relay observes quality → proposes switch to all clients
+
+The only difference is WHO makes the decision (client vs relay) and HOW many participants need to agree (2 vs N).
+
+Implementation strategy: build for P2P first (simpler, 2 parties), then wrap the same logic with relay-mediated signals for SFU mode.
+
+## Milestones
+
+| Phase | Scope | Effort |
+|-------|-------|--------|
+| 1 | Relay-side quality monitor (per-participant tracking) | 1 day |
+| 2 | Downgrade signal (immediate, match weakest) | 1 day |
+| 3 | Client handling of QualityDirective | 1 day (both engines) |
+| 4 | Upgrade proposal + negotiation protocol | 2 days |
+| 5 | P2P quality adaptation (direct observation) | 1 day |
+| 6 | Per-participant asymmetric encoding (Option 2) | 1 day |

docs/PRD-delegated-trust.md

@@ -0,0 +1,170 @@
+# PRD: Delegated Trust for Relay Federation
+
+## Problem
+
+In the current federation model, when Relay 1 trusts Relay 2, and Relay 2 forwards media from Relay 3, Relay 1 has no way to know or control that Relay 3's traffic is reaching it. This is a trust gap — any relay in the chain can introduce untrusted traffic.
+
+**Example:** Relay 1 (trusted zone) ←→ Relay 2 (hub) ←→ Relay 3 (unknown)
+
+Relay 1 explicitly trusts Relay 2. But Relay 2 forwards Relay 3's media to Relay 1 without Relay 1's consent. Relay 1 receives media that originated from an entity it never approved.
+
+## Solution
+
+Add a `delegate` flag to `[[trusted]]` entries. When `delegate = true`, the relay accepts media forwarded through the trusted peer from relays that the trusted peer vouches for. When `delegate = false` (default), only media originating from explicitly trusted/peered relays is accepted.
+
+## Trust Levels
+
+| Config | Meaning |
+|--------|---------|
+| `[[peers]]` | "I connect to you and trust your identity" |
+| `[[trusted]]` | "I accept connections from you" |
+| `[[trusted]] delegate = true` | "I accept connections from you AND from relays you vouch for" |
+| No entry | "I reject your connections and drop your forwarded media" |
+
+## Configuration
+
+```toml
+# Relay 1: trusts Relay 2 and delegates trust
+[[trusted]]
+fingerprint = "relay-2-tls-fingerprint"
+label = "Relay 2 (Hub)"
+delegate = true    # Accept relays that Relay 2 forwards from
+
+# Without delegate (default = false):
+[[trusted]]
+fingerprint = "relay-4-tls-fingerprint"
+label = "Relay 4"
+# delegate = false  (implicit default)
+# Only direct media from Relay 4 is accepted
+```
+
+## Protocol Changes
+
+### Relay-to-Relay Media Authorization
+
+When Relay 2 forwards media from Relay 3 to Relay 1, the datagram needs to carry origin information so Relay 1 can decide whether to accept it.
+
+**Option A: Origin tag in datagram** (recommended)
+
+Extend the federation datagram format:
+```
+[room_hash: 8 bytes][origin_relay_fp: 8 bytes][media_packet]
+```
+
+The 8-byte origin fingerprint identifies which relay originally produced the media. The forwarding relay (Relay 2) sets this to the source relay's fingerprint. Relay 1 checks:
+1. Is the origin relay directly trusted? → accept
+2. Is the forwarding relay trusted with `delegate = true`? → accept
+3. Otherwise → drop
+
+**Option B: Trust announcement signal**
+
+When Relay 2 connects to Relay 1, it sends a `FederationTrustChain` signal listing which relays it will forward from:
+```rust
+FederationTrustChain {
+    /// Fingerprints of relays this peer may forward media from
+    vouched_relays: Vec<String>,
+}
+```
+
+Relay 1 checks each fingerprint against its policy:
+- If Relay 2 has `delegate = true` in Relay 1's config → accept all listed relays
+- If Relay 2 has `delegate = false` → reject, only accept direct media from Relay 2
+
+Option B is simpler to implement (no datagram format change) but less granular.
+
+### Recommended: Option B for v1, Option A for v2
+
+Option B is simpler — the trust chain is established at connection time, not per-datagram. The forwarding relay announces what it will forward, and the receiving relay approves or rejects upfront.
+
+## Implementation
+
+### Config Changes
+
+```rust
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct TrustedConfig {
+    pub fingerprint: String,
+    #[serde(default)]
+    pub label: Option<String>,
+    /// When true, also accept media forwarded through this relay from
+    /// relays it vouches for. Default: false.
+    #[serde(default)]
+    pub delegate: bool,
+}
+```
+
+### Federation Signal
+
+```rust
+/// Sent after FederationHello — lists relays this peer will forward from.
+FederationTrustChain {
+    /// TLS fingerprints of relays whose media may be forwarded through us.
+    vouched_relays: Vec<String>,
+}
+```
+
+### Forwarding Authorization
+
+In `handle_datagram`, before forwarding media to local participants:
+
+```rust
+// Check if we should accept this forwarded media
+let is_authorized = if source_is_direct_peer {
+    true  // Direct peer, always accepted
+} else {
+    // Check if the forwarding peer has delegate=true
+    let forwarding_peer = fm.find_trusted_by_fingerprint(forwarding_peer_fp);
+    forwarding_peer.map(|t| t.delegate).unwrap_or(false)
+};
+
+if !is_authorized {
+    warn!("dropping forwarded media from unauthorized relay chain");
+    return;
+}
+```
+
+### Relay 2 (Hub) Behavior
+
+When Relay 2 receives `FederationTrustChain` queries from peers:
+1. Collect all directly connected peer fingerprints
+2. Send `FederationTrustChain { vouched_relays }` to each peer
+3. When a new relay connects, update all peers' trust chains
+
+### Anti-Spam Properties
+
+| Attack | Mitigation |
+|--------|-----------|
+| Unknown relay connects to hub | Hub rejects (not in `[[trusted]]`) |
+| Hub forwards spam relay's media | Receiving relay checks delegate flag, drops if false |
+| Relay spoofs origin fingerprint | Origin tag is set by the forwarding relay, not the source. The forwarding relay is trusted, so if it lies about origin, the trust is misplaced at the config level. |
+| Chain amplification (A→B→C→D→...) | TTL on forwarded datagrams (decrement at each hop, drop at 0). Default TTL=2 (one intermediate relay). |
+
+## TTL for Chain Length
+
+Add a TTL byte to the federation datagram to limit chain depth:
+
+```
+[room_hash: 8 bytes][ttl: 1 byte][media_packet]
+```
+
+- Default TTL = 2 (allows one intermediate relay: A→B→C)
+- Each forwarding relay decrements TTL
+- When TTL = 0, don't forward further (only deliver to local participants)
+- Configurable per-relay: `max_federation_hops = 2`
+
+## Milestones
+
+| Phase | Scope | Effort |
+|-------|-------|--------|
+| 1 | Add `delegate` field to `TrustedConfig` | 0.5 day |
+| 2 | `FederationTrustChain` signal + announcement | 1 day |
+| 3 | Authorization check in `handle_datagram` | 0.5 day |
+| 4 | TTL in federation datagrams | 0.5 day |
+| 5 | Testing: authorized vs unauthorized forwarding | 0.5 day |
+
+## Non-Goals (v1)
+
+- Per-room trust policies (trust Relay X only for room "android")
+- Dynamic trust negotiation (relays negotiate trust level at runtime)
+- Revocation (removing a relay from trust chain requires config edit + restart)
+- Cryptographic proof of origin (signed datagrams from source relay)

docs/PRD-desktop-direct-calling.md

@@ -0,0 +1,22 @@
+# PRD: Desktop Direct Calling — Backport SignalManager
+
+## Problem
+
+The desktop Tauri app has the direct calling UI (Room/Direct Call toggle, Register, Call buttons) but the backend uses inline async code in `main.rs` instead of a proper `SignalManager`. This needs to be backported from the Android refactor.
+
+## Tasks
+
+1. **Create `signal_mgr.rs` for desktop** — same pattern as Android, or reuse the crate directly
+2. **Wire into Tauri commands** — `register_signal` should use `SignalManager::connect()` + `run_recv_loop()` on a dedicated thread
+3. **State polling** — `get_signal_status` should call `SignalManager::get_state_json()`
+4. **place_call / answer_call** — delegate to SignalManager methods
+5. **Merge android branch into desktop branch** — resolve the 37 desktop-only + 90 android-only commit divergence
+6. **Test** — Android calls Desktop, Desktop calls Android
+
+## UI Fixes
+
+1. **Default alias** — generate random name on first start (like Android does)
+2. **Default room** — change from "android" to "general"
+3. **Fingerprint display** — ensure full `xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx` format (not truncated)
+4. **Deregister button** — ability to disconnect signal channel
+5. **Call state reset** — after hangup, return to "Registered" state, not stuck on "Ringing"

docs/PRD-mtu-discovery.md

@@ -0,0 +1,59 @@
+# PRD: QUIC Path MTU Discovery
+
+## Problem
+
+WarzonePhone uses conservative 1200-byte QUIC datagrams. Some network paths support larger MTUs (1400+), wasting bandwidth. Some broken paths (VPNs, tunnels, double-NAT, cellular) have MTU < 1200, causing silent packet drops — this may explain why Opus 64k fails on some paths while 24k works (larger encoded frames + FEC repair packets).
+
+## Solution
+
+Enable Quinn's built-in Path MTU Discovery (PMTUD) and handle edge cases:
+1. PMTUD probes larger packet sizes and discovers the actual path MTU
+2. Graceful fallback when datagrams exceed discovered MTU
+3. Expose MTU in metrics for debugging
+
+## Implementation
+
+### Phase 1: Enable PMTUD in Quinn
+
+`crates/wzp-transport/src/config.rs` — update `transport_config()`:
+
+```rust
+// Enable PMTUD (Quinn default is enabled, but we should ensure it)
+config.mtu_discovery_config(Some(quinn::MtuDiscoveryConfig::default()));
+
+// Set minimum MTU for safety (some paths can't handle 1200)
+// Quinn default min is 1200, which is the QUIC spec minimum
+```
+
+Quinn's `MtuDiscoveryConfig` has:
+- `interval`: how often to probe (default: 600s)
+- `upper_bound`: max MTU to probe (default: 1452 for IPv4)
+- `minimum_change`: min MTU increase to be worth probing (default: 20)
+
+### Phase 2: Handle MTU-related Failures
+
+In federation forwarding (`send_raw_datagram`), if the datagram exceeds the connection's current MTU, Quinn returns an error. Handle gracefully:
+- Log warning with packet size vs MTU
+- Drop the packet (don't crash)
+- Track in metrics: `wzp_relay_mtu_exceeded_total`
+
+### Phase 3: Codec-Aware MTU
+
+When the path MTU is small, the relay or client should:
+- Prefer lower-bitrate codecs (smaller packets)
+- Reduce FEC ratio (fewer repair packets)
+- This feeds into the adaptive quality system
+
+### Phase 4: Expose MTU in Stats
+
+- Add `path_mtu` to relay metrics (per peer)
+- Add `path_mtu` to client stats (visible in UI)
+- Log MTU on connection establishment
+
+## Non-Goals (v1)
+
+- Datagram fragmentation (QUIC datagrams are atomic — either fit or don't)
+- Manual MTU override per relay config
+- MTU-based codec selection (future, needs adaptive quality)
+
+## Effort: 1 day

docs/PRD-p2p-direct.md

@@ -0,0 +1,146 @@
+# PRD: Peer-to-Peer Direct Calls (No Relay)
+
+## Problem
+
+All calls currently route through a relay, even 1-on-1 calls between clients that could reach each other directly. This adds latency (2x hop), creates a single point of failure, and requires trusting the relay operator (even though media is encrypted, the relay sees metadata).
+
+## Solution
+
+For 1-on-1 calls, clients attempt a direct QUIC connection using STUN-discovered addresses. If NAT traversal succeeds, media flows directly between peers. If it fails, fall back to relay-assisted mode (current behavior).
+
+## Architecture
+
+```
+Preferred (P2P):
+  Client A ←──QUIC direct──→ Client B
+  (no relay in media path, true E2E)
+
+Fallback (Relay):
+  Client A ──→ Relay ──→ Client B
+  (current model)
+
+Hybrid discovery:
+  Client A → Relay (signaling only) → Client B
+       ↓                                    ↓
+    STUN server                        STUN server
+       ↓                                    ↓
+    Discover public IP:port          Discover public IP:port
+       ↓                                    ↓
+    Exchange candidates via relay signaling
+       ↓                                    ↓
+    Attempt direct QUIC connection ←──→
+```
+
+## Why P2P = True E2E
+
+- QUIC TLS handshake establishes encrypted tunnel directly between A and B
+- No third party sees the traffic
+- Certificate pinning via identity fingerprints: each client derives their TLS cert from their Ed25519 seed (same as relay identity). During QUIC handshake, both sides verify the peer's cert fingerprint against the known identity
+- MITM elimination: if A knows B's fingerprint (from prior call, QR code, or identity server), any interceptor presents a different cert → fingerprint mismatch → connection rejected
+- Stronger guarantee than relay-assisted: user doesn't need to trust relay operator
+
+## Requirements
+
+### Phase 1: STUN Discovery
+
+1. **STUN client**: lightweight UDP-based STUN client to discover public IP:port
+   - Use existing public STUN servers (stun.l.google.com:19302, etc.)
+   - Or run a STUN server alongside the relay
+   - Discover: local addresses, server-reflexive addresses (STUN), relay candidates (TURN/relay fallback)
+
+2. **Candidate gathering**: on call initiation, gather all candidates:
+   - Host candidates: local network interfaces
+   - Server-reflexive: STUN-discovered public IP:port
+   - Relay candidate: the relay's address (fallback)
+
+3. **Candidate exchange**: via relay signaling channel (existing `IceCandidate` signal message)
+   - A sends candidates to relay → relay forwards to B
+   - B sends candidates to relay → relay forwards to A
+
+### Phase 2: Direct Connection
+
+1. **QUIC hole punching**: both clients simultaneously attempt QUIC connections to each other's candidates
+   - Quinn supports connecting to multiple addresses
+   - First successful connection wins
+   - Timeout after 3 seconds, fall back to relay
+
+2. **Identity verification**: during QUIC handshake, verify peer's TLS cert fingerprint
+   - `server_config_from_seed()` already exists — derive client cert from identity seed
+   - Both sides present certs (mutual TLS)
+   - Verify fingerprint matches expected identity
+
+3. **Media flow**: once connected, use existing `QuinnTransport` for media + signals
+   - Same `send_media()` / `recv_media()` API
+   - Same codec pipeline, FEC, jitter buffer
+   - No code changes needed in the call engine
+
+### Phase 3: Adaptive Quality (P2P)
+
+P2P connections have direct quality visibility — no relay middleman:
+
+1. Both clients observe RTT, loss, jitter directly from QUIC stats
+2. Adapt codec quality based on direct observations
+3. Since only 2 participants, coordinated switching is simple: propose → ack → switch
+
+This is the simplest case for adaptive quality. Once proven, backport the logic to relay-assisted mode.
+
+### Phase 4: Hybrid Mode
+
+1. **Call initiation**: always connect to relay for signaling
+2. **Parallel attempt**: while relay call is active, attempt P2P in background
+3. **Seamless migration**: if P2P succeeds, migrate media path from relay to direct
+   - Both clients switch simultaneously
+   - Relay connection kept alive for signaling (presence, room updates)
+4. **Fallback**: if P2P connection drops, seamlessly fall back to relay
+
+## Security Properties
+
+| Property | Relay Mode | P2P Mode |
+|----------|-----------|----------|
+| Encryption | ChaCha20-Poly1305 (app layer) | QUIC TLS 1.3 + ChaCha20-Poly1305 |
+| Key exchange | Via relay signaling | Direct QUIC handshake |
+| Identity verification | TOFU (server fingerprint) | Mutual TLS cert pinning |
+| Metadata privacy | Relay sees who talks to whom | No third party sees anything |
+| MITM resistance | Depends on relay trust | Strong (cert pinning) |
+| Forward secrecy | ECDH ephemeral keys | QUIC built-in + app-layer rekey |
+
+## Implementation Notes
+
+### STUN in Rust
+
+Use `stun-rs` or `webrtc-rs` crate for STUN client. Minimal: just need Binding Request/Response to discover server-reflexive address.
+
+### Quinn Hole Punching
+
+Quinn's `Endpoint` can both listen and connect. For hole punching:
+```rust
+let endpoint = create_endpoint(bind_addr, Some(server_config))?;
+// Send connect to peer's address (opens NAT pinhole)
+let conn = connect(&endpoint, peer_addr, "peer", client_config).await?;
+// Simultaneously, peer connects to our address
+// First successful handshake wins
+```
+
+### Client TLS Certificate
+
+Already have `server_config_from_seed()` for relays. Create `client_config_from_seed()` that presents a TLS client certificate derived from the identity seed. The peer verifies this cert's fingerprint.
+
+### Signaling via Relay
+
+The existing relay connection carries `IceCandidate` signals. No new infrastructure needed — just use the relay as a dumb signaling pipe for candidate exchange.
+
+## Non-Goals (v1)
+
+- SFU over P2P (P2P is 1-on-1 only; multi-party uses relay SFU)
+- TURN server (relay acts as the fallback, no separate TURN)
+- mDNS local discovery (future)
+- Mesh P2P for multi-party (future, complex)
+
+## Milestones
+
+| Phase | Scope | Effort |
+|-------|-------|--------|
+| 1 | STUN client + candidate gathering | 2 days |
+| 2 | QUIC hole punching + identity verification | 3 days |
+| 3 | Adaptive quality on P2P connection | 2 days |
+| 4 | Hybrid mode (relay + P2P, seamless migration) | 3 days |

docs/PRD-protocol-analyzer.md

@@ -0,0 +1,178 @@
+# PRD: Protocol Analyzer & Debug Tap
+
+## 1. Relay-Side Metadata Tap (`--debug-tap`)
+
+### Problem
+
+When debugging federation, codec issues, or packet flow problems, there's no visibility into what's actually flowing through the relay. You have to guess from client-side logs.
+
+### Solution
+
+A `--debug-tap <room>` flag on the relay that logs every packet's **header metadata** for a specific room (or all rooms with `--debug-tap *`). No decryption needed — the MediaHeader is not encrypted, only the audio payload is.
+
+### Output Format
+
+```
+[12:00:00.123] TAP room=test dir=in  src=192.168.1.5:54321 seq=1234 codec=Opus24k ts=24000 fec_block=5 fec_sym=2 repair=false len=87
+[12:00:00.123] TAP room=test dir=out dst=192.168.1.6:54322 seq=1234 codec=Opus24k ts=24000 fec_block=5 fec_sym=2 repair=false len=87 fan_out=2
+[12:00:00.143] TAP room=test dir=in  src=192.168.1.5:54321 seq=1235 codec=Opus24k ts=24960 fec_block=5 fec_sym=3 repair=false len=91
+[12:00:00.500] TAP room=test dir=in  src=192.168.1.6:54322 seq=0042 codec=Codec2_1200 ts=40000 fec_block=1 fec_sym=0 repair=false len=6
+[12:00:01.000] TAP room=test SIGNAL type=RoomUpdate count=3 participants=[Alice,Bob,Charlie]
+[12:00:05.000] TAP room=test STATS period=5s in_pkts=250 out_pkts=500 fan_out_avg=2.0 loss_detected=0 codecs_seen=[Opus24k,Codec2_1200]
+```
+
+### What it shows
+
+- **Per-packet**: direction, source/dest, sequence number, codec ID, timestamp, FEC block/symbol, repair flag, payload size
+- **Signals**: RoomUpdate, FederationRoomJoin/Leave, handshake events
+- **Periodic stats**: packets in/out, average fan-out, codecs seen, detected sequence gaps (loss)
+- **Federation**: room-hash tagged datagrams with source/dest relay
+
+### Implementation
+
+**File:** `crates/wzp-relay/src/room.rs` — in `run_participant_plain()` and `run_participant_trunked()`
+
+After receiving a packet and before forwarding:
+```rust
+if debug_tap_enabled {
+    let h = &pkt.header;
+    info!(
+        room = %room_name,
+        dir = "in",
+        src = %addr,
+        seq = h.seq,
+        codec = ?h.codec_id,
+        ts = h.timestamp,
+        fec_block = h.fec_block,
+        fec_sym = h.fec_symbol,
+        repair = h.is_repair,
+        len = pkt.payload.len(),
+        "TAP"
+    );
+}
+```
+
+**Activation:** `--debug-tap <room_name>` CLI flag, or `debug_tap = "test"` / `debug_tap = "*"` in TOML config.
+
+**Performance:** Only active when enabled. When enabled, adds one `info!()` log per packet per direction. At 50 fps × 5 participants = 500 log lines/sec — acceptable for debugging, not for production.
+
+**Output options:**
+- Default: tracing log (stderr)
+- `--debug-tap-file <path>`: write to a dedicated file (JSONL format for machine parsing)
+
+### Effort: 0.5 day
+
+---
+
+## 2. Full Protocol Analyzer (Standalone Tool)
+
+### Problem
+
+The metadata tap shows packet flow but can't inspect audio content, verify encryption, or measure audio quality. For deep debugging (codec issues, resampling bugs, encryption mismatches), you need to see the actual decrypted audio.
+
+### Solution
+
+A standalone `wzp-analyzer` binary that either:
+- **A)** Acts as a transparent proxy between client and relay (MITM mode)
+- **B)** Reads a pcap/capture file with QUIC session keys (passive mode)
+- **C)** Runs as a special "observer" client that joins a room in listen-only mode with all participants' consent
+
+### Architecture
+
+**Option C (recommended — simplest, no MITM):**
+
+```
+                    ┌──────────────┐
+  Client A ────────►│    Relay     │◄──────── Client B
+                    │              │
+                    │   (SFU)      │◄──────── wzp-analyzer
+                    └──────────────┘          (observer mode)
+                                              │
+                                              ▼
+                                    ┌──────────────────┐
+                                    │  Decode + Analyze │
+                                    │  - Packet timing  │
+                                    │  - Codec decode   │
+                                    │  - Audio quality  │
+                                    │  - Jitter stats   │
+                                    │  - Waveform plot  │
+                                    └──────────────────┘
+```
+
+The analyzer joins the room as a regular participant (receives all media via SFU forwarding) but doesn't send audio. It decodes everything it receives and produces analysis.
+
+**Limitation:** End-to-end encrypted payloads can't be decoded without session keys. The analyzer would either:
+1. Need the session key (shared out-of-band for debugging)
+2. Or only analyze unencrypted headers + timing (same as the relay tap, but from client perspective with jitter buffer simulation)
+
+For now, since encryption is not fully enforced in the current codebase (the crypto session is established but the actual ChaCha20 encryption of payloads is TODO in some paths), the analyzer can decode raw Opus/Codec2 payloads directly.
+
+### Features
+
+**Real-time display (TUI):**
+```
+┌─ wzp-analyzer: room "podcast" on 193.180.213.68:4433 ─────────────┐
+│                                                                      │
+│  Participants: Alice (Opus24k), Bob (Codec2_3200)                   │
+│                                                                      │
+│  Alice ────────────────────────────────────────                      │
+│  seq: 5234  codec: Opus24k  ts: 125760  loss: 0.2%  jitter: 3ms   │
+│  RMS: 4521  peak: 15280  silence: no                                │
+│  FEC blocks: 1046/1046 complete (0 recovered)                       │
+│  ▁▂▃▅▇█▇▅▃▂▁▁▂▃▅▇█▇▅▃▂▁  (waveform last 1s)                     │
+│                                                                      │
+│  Bob ──────────────────────────────────────                          │
+│  seq: 2617  codec: Codec2_3200  ts: 62800  loss: 1.5%  jitter: 8ms│
+│  RMS: 1250  peak: 6800  silence: no                                 │
+│  FEC blocks: 523/525 complete (4 recovered)                         │
+│  ▁▁▂▃▅▇▅▃▂▁▁▁▂▃▅▇▅▃▂▁▁  (waveform last 1s)                     │
+│                                                                      │
+│  Total: 7851 pkts recv, 0 pkts sent, 2 participants                │
+│  Uptime: 2m 35s                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+**Recorded analysis:**
+- Save all received packets to a capture file
+- Post-session report: per-participant stats, quality timeline, codec switches, packet loss patterns
+- Export decoded audio as WAV per participant (if decryptable)
+
+**Quality metrics per participant:**
+- Packet loss % (from sequence gaps)
+- Jitter (inter-arrival time variance)
+- Codec switches (timestamps + reasons)
+- RMS audio level over time
+- Silence detection
+- FEC recovery rate
+- Round-trip estimates (from Ping/Pong if available)
+
+### Implementation
+
+**Binary:** `wzp-analyzer` (new crate or subcommand of `wzp-client`)
+
+```
+wzp-analyzer 193.180.213.68:4433 --room podcast
+wzp-analyzer 193.180.213.68:4433 --room podcast --record capture.wzp
+wzp-analyzer --replay capture.wzp --report report.html
+```
+
+**Dependencies:**
+- Existing: `wzp-transport`, `wzp-proto`, `wzp-codec`, `wzp-crypto`
+- New: `ratatui` for TUI display (optional)
+
+### Phases
+
+| Phase | Scope | Effort |
+|-------|-------|--------|
+| 1 | Header-only analysis: join room, log packet metadata, show per-participant stats (TUI) | 2 days |
+| 2 | Audio decode: decode Opus/Codec2 payloads (unencrypted path), show waveform + RMS | 1-2 days |
+| 3 | Capture/replay: save packets to file, replay offline with full analysis | 1 day |
+| 4 | HTML report: post-session quality report with charts | 2 days |
+| 5 | Encrypted payload support: accept session keys, decrypt ChaCha20 | 1 day |
+
+### Non-Goals (v1)
+
+- Active probing (sending test patterns)
+- Modifying packets in transit
+- Automated quality scoring (MOS estimation)
+- Video support

docs/USER_GUIDE.md

@@ -0,0 +1,508 @@
+# WarzonePhone User Guide
+
+This guide covers all WarzonePhone client applications: Desktop (Tauri), Android, CLI, and Web.
+
+## Desktop Client (Tauri)
+
+The desktop client is a Tauri application with a native Rust audio engine and a web-based UI. It runs on macOS, Windows, and Linux.
+
+### Connect Screen
+
+When you launch the desktop client, you see the connect screen with:
+
+- **Relay selector** -- click the relay button to open the Manage Relays dialog. Shows relay name, address, connection status (verified/new/changed/offline), and RTT latency
+- **Room** -- enter a room name. Clients in the same room hear each other. Room names are hashed before being sent to the relay for privacy
+- **Alias** -- your display name shown to other participants
+- **OS Echo Cancel** -- checkbox to enable macOS VoiceProcessingIO (Apple's FaceTime-grade AEC). Strongly recommended when using speakers
+- **Connect button** -- connects to the selected relay and joins the room
+- **Identity info** -- your identicon and fingerprint are shown at the bottom. Click to copy
+
+Recent rooms are displayed below the form for quick reconnection. Click any recent room to select it and its associated relay.
+
+### In-Call Screen
+
+Once connected, the in-call screen shows:
+
+- **Room name** and **call timer** at the top
+- **Status indicator** -- green when connected, yellow when reconnecting
+- **Audio level meter** -- real-time visualization of outgoing audio
+- **Participant list** -- identicon, alias, and fingerprint for each participant. Your own entry is highlighted with a badge
+- **Controls** -- Mic toggle, Hang Up, Speaker toggle
+- **Stats bar** -- TX and RX frame rates
+
+### Settings Panel
+
+Open with the gear icon or **Cmd+,** (Ctrl+, on Windows/Linux). Contains:
+
+#### Connection
+
+- **Default Room** -- room name used on next connect
+- **Alias** -- display name
+
+#### Audio
+
+- **Quality slider** -- 5 levels:
+
+  | Position | Profile | Description |
+  |----------|---------|-------------|
+  | 0 | Auto | Adaptive quality based on network conditions |
+  | 1 | Opus 24k | Good conditions (28.8 kbps with FEC) |
+  | 2 | Opus 6k | Degraded conditions (9.0 kbps with FEC) |
+  | 3 | Codec2 3.2k | Poor conditions (4.8 kbps with FEC) |
+  | 4 | Codec2 1.2k | Catastrophic conditions (2.4 kbps with FEC) |
+
+- **OS Echo Cancellation** -- macOS VoiceProcessingIO toggle
+- **Automatic Gain Control** -- normalize mic volume
+
+#### Identity
+
+- **Fingerprint** -- your public identity fingerprint
+- **Identity file** -- stored at `~/.wzp/identity`
+
+#### Recent Rooms
+
+- History of recently joined rooms with relay association
+- Clear History button
+
+### Manage Relays Dialog
+
+Open by clicking the relay selector button on the connect screen:
+
+- **Relay list** -- each entry shows name, address, identicon (from server fingerprint), lock status, and RTT
+- **Select** -- click a relay to make it the default
+- **Remove** -- click the X button to delete a relay
+- **Add Relay** -- enter name and host:port to add a new relay
+- **Ping** -- relays are automatically pinged when the dialog opens. RTT and server fingerprint are updated
+
+### Key Change Warning Dialog
+
+If a relay's TLS fingerprint has changed since your last connection, a warning dialog appears:
+
+- Shows the previously known fingerprint and the new fingerprint
+- **Accept New Key** -- trust the new fingerprint and proceed
+- **Cancel** -- abort the connection
+
+This is the TOFU (Trust on First Use) model. Fingerprint changes typically mean the relay was restarted with a new identity. However, they could also indicate a man-in-the-middle attack.
+
+### Keyboard Shortcuts
+
+| Shortcut | Action | Context |
+|----------|--------|---------|
+| **m** | Toggle microphone | In-call |
+| **s** | Toggle speaker | In-call |
+| **q** | Hang up | In-call |
+| **Cmd+,** (Ctrl+,) | Open/close settings | Any |
+| **Escape** | Close dialog/settings | Any |
+| **Enter** | Connect | Connect screen (when room/alias field is focused) |
+
+### Audio Engine
+
+The desktop audio engine uses:
+
+- **CPAL** for audio I/O (CoreAudio on macOS, WASAPI on Windows, ALSA on Linux)
+- **VoiceProcessingIO** on macOS for OS-level echo cancellation (opt-in via checkbox)
+- **Lock-free SPSC ring buffers** between audio threads and network threads
+- **Direct playout** -- no jitter buffer on the client (the relay buffers instead)
+- Audio callbacks deliver 512 f32 samples at 48 kHz on macOS (accumulated to 960-sample frames for codec)
+
+#### Audio Quality Notes
+
+- Always use **Release builds** for real-time audio. Debug builds are too slow for wzp-codec, nnnoiseless, audiopus, and raptorq
+- VoiceProcessingIO is strongly recommended on macOS. Software AEC does not work well with the round-trip latency (~35-45ms)
+- The quality slider only affects the **encode** side. Decoding always accepts all codecs
+
+### Auto-Reconnect
+
+If the connection drops, the client automatically attempts to reconnect with exponential backoff (1s, 2s, 4s, 8s, capped at 10s). After 5 failed attempts, the client returns to the connect screen. The status dot shows yellow during reconnection.
+
+## Android Client
+
+The Android client is built with Kotlin and Jetpack Compose, using JNI to call the Rust audio engine.
+
+### Call Screen
+
+The main call screen shows:
+
+- **Server selector** -- tap to choose from configured servers
+- **Room name** -- enter the room to join
+- **Connect/Disconnect** button
+- **Participant list** with identicons and aliases
+- **Audio level visualization**
+- **Mute/Unmute** button
+
+### Settings Screen
+
+The settings screen is organized into sections:
+
+#### Identity
+
+- **Display Name** -- your alias shown to other participants
+- **Fingerprint** -- displayed with an identicon. Tap to copy
+- **Copy Key** -- copy the 64-character hex seed to clipboard for backup
+- **Restore Key** -- paste a previously backed-up hex seed to restore your identity
+
+#### Audio Defaults
+
+- **Voice Volume** -- playout gain slider (-20 dB to +20 dB)
+- **Mic Gain** -- capture gain slider (-20 dB to +20 dB)
+- **Echo Cancellation (AEC)** -- toggle Android's built-in AEC. Disable if audio sounds distorted
+- **Quality slider** -- 8 levels from best to lowest:
+
+  | Position | Profile | Bitrate | Color |
+  |----------|---------|---------|-------|
+  | 0 | Studio 64k | 70.4 kbps | Green |
+  | 1 | Studio 48k | 52.8 kbps | Green |
+  | 2 | Studio 32k | 35.2 kbps | Green |
+  | 3 | Auto | Adaptive | Yellow-green |
+  | 4 | Opus 24k | 28.8 kbps | Yellow-green |
+  | 5 | Opus 6k | 9.0 kbps | Yellow |
+  | 6 | Codec2 3.2k | 4.8 kbps | Orange |
+  | 7 | Codec2 1.2k | 2.4 kbps | Red |
+
+  Note: "Decode always accepts all codecs" -- the quality setting only affects encoding.
+
+#### Servers
+
+- **Server chips** -- tap to select, X to remove (built-in servers cannot be removed)
+- **Add Server** -- enter host, port (default 4433), and optional label
+- **Force Ping** -- servers are pinged on dialog open to measure RTT
+
+#### Network
+
+- **Prefer IPv6** -- toggle to prefer IPv6 connections when available
+
+#### Room
+
+- **Default Room** -- the room name pre-filled on the call screen
+
+### Identity Backup and Restore
+
+Your identity is a 32-byte seed stored as a 64-character hex string. To back up:
+
+1. Go to Settings > Identity
+2. Tap **Copy Key**
+3. Store the hex string securely
+
+To restore on a new device:
+
+1. Go to Settings > Identity
+2. Tap **Restore Key**
+3. Paste the 64-character hex string
+4. Tap **Restore** (key is staged)
+5. Tap **Save** to apply
+
+The same seed produces the same fingerprint on any device or platform.
+
+## CLI Client (wzp-client)
+
+The CLI client is a command-line tool for testing, recording, and live audio.
+
+### Usage
+
+```
+wzp-client [options] [relay-addr]
+```
+
+Default relay address: `127.0.0.1:4433`
+
+### Flags Reference
+
+| Flag | Description |
+|------|-------------|
+| `--live` | Live mic/speaker mode. Requires `--features audio` at build time |
+| `--send-tone <secs>` | Send a 440 Hz test tone for N seconds |
+| `--send-file <file>` | Send a raw PCM file (48 kHz mono s16le) |
+| `--record <file.raw>` | Record received audio to raw PCM file |
+| `--echo-test <secs>` | Run automated echo quality test for N seconds. Produces a windowed analysis with loss%, SNR, correlation |
+| `--drift-test <secs>` | Run automated clock-drift measurement for N seconds |
+| `--sweep` | Run jitter buffer parameter sweep (local, no network). Tests different buffer configurations |
+| `--seed <hex>` | Identity seed as 64 hex characters. Compatible with featherChat |
+| `--mnemonic <words...>` | Identity seed as BIP39 mnemonic (24 words). All remaining non-flag words are consumed |
+| `--room <name>` | Room name. Hashed before sending for privacy |
+| `--token <token>` | featherChat bearer token for relay authentication |
+| `--metrics-file <path>` | Write JSONL telemetry to file (1 line/sec) |
+| `--help`, `-h` | Print help and exit |
+
+### Common Usage Patterns
+
+#### Connectivity Test (Silence)
+
+```bash
+# Send 250 silence frames (5 seconds) and exit
+wzp-client 127.0.0.1:4433
+```
+
+#### Live Audio Call
+
+```bash
+# Terminal 1
+wzp-relay
+
+# Terminal 2: Alice
+wzp-client --live --room myroom 127.0.0.1:4433
+
+# Terminal 3: Bob
+wzp-client --live --room myroom 127.0.0.1:4433
+```
+
+Both capture from mic and play received audio. Press Ctrl+C to stop.
+
+#### Send Test Tone and Record
+
+```bash
+# Terminal 1
+wzp-relay
+
+# Terminal 2: Send 10 seconds of 440 Hz tone
+wzp-client --send-tone 10 127.0.0.1:4433
+
+# Terminal 3: Record what is received
+wzp-client --record call.raw 127.0.0.1:4433
+```
+
+Play the recording:
+
+```bash
+ffplay -f s16le -ar 48000 -ac 1 call.raw
+```
+
+#### Send Audio File
+
+```bash
+# Convert to raw PCM first
+ffmpeg -i song.mp3 -f s16le -ar 48000 -ac 1 song.raw
+
+# Send through relay
+wzp-client --send-file song.raw 127.0.0.1:4433
+```
+
+#### Echo Quality Test
+
+```bash
+wzp-relay &
+wzp-client --echo-test 30 127.0.0.1:4433
+```
+
+Produces a windowed analysis showing loss percentage, SNR, correlation, and quality degradation trends.
+
+#### Clock Drift Test
+
+```bash
+wzp-relay &
+wzp-client --drift-test 60 127.0.0.1:4433
+```
+
+Measures clock drift between the send and receive paths over the specified duration.
+
+#### Jitter Buffer Sweep
+
+```bash
+# Runs locally, no network needed
+wzp-client --sweep
+```
+
+Tests different jitter buffer configurations and prints results.
+
+#### With Identity and Auth
+
+```bash
+# Using hex seed
+wzp-client --seed 0123456789abcdef...64chars --room secure-room --token my-bearer-token relay.example.com:4433
+
+# Using BIP39 mnemonic
+wzp-client --mnemonic abandon abandon abandon ... zoo --room secure-room relay.example.com:4433
+```
+
+#### With JSONL Telemetry
+
+```bash
+wzp-client --live --metrics-file /tmp/call.jsonl relay.example.com:4433
+```
+
+Writes one JSON object per second:
+
+```json
+{
+  "ts": "2026-04-07T12:00:00Z",
+  "buffer_depth": 45,
+  "underruns": 0,
+  "overruns": 0,
+  "loss_pct": 1.2,
+  "rtt_ms": 34,
+  "jitter_ms": 8,
+  "frames_sent": 50,
+  "frames_received": 49,
+  "quality_profile": "GOOD"
+}
+```
+
+### Audio File Format
+
+All raw PCM files use:
+
+| Property | Value |
+|----------|-------|
+| Sample rate | 48 kHz |
+| Channels | 1 (mono) |
+| Sample format | signed 16-bit little-endian (s16le) |
+
+Conversion commands:
+
+```bash
+# WAV to raw PCM
+ffmpeg -i input.wav -f s16le -ar 48000 -ac 1 output.raw
+
+# MP3 to raw PCM
+ffmpeg -i input.mp3 -f s16le -ar 48000 -ac 1 output.raw
+
+# Raw PCM to WAV
+ffmpeg -f s16le -ar 48000 -ac 1 -i input.raw output.wav
+
+# Play raw PCM
+ffplay -f s16le -ar 48000 -ac 1 file.raw
+```
+
+## Web Client (Browser)
+
+The web client runs in a browser via the wzp-web bridge server.
+
+### Setup
+
+```bash
+# Start relay
+wzp-relay
+
+# Start web bridge
+wzp-web --port 8080 --relay 127.0.0.1:4433
+
+# For remote access (requires TLS for mic)
+wzp-web --port 8443 --relay 127.0.0.1:4433 --tls
+```
+
+Open `http://localhost:8080/room-name` (or `https://...` with TLS).
+
+### Features
+
+- **Open mic** (default) and **push-to-talk** modes
+- PTT via on-screen button, mouse hold, or spacebar
+- Audio level meter
+- Auto-reconnection on disconnect
+
+### Audio Processing
+
+The web client uses AudioWorklet (preferred) with a ScriptProcessorNode fallback:
+
+- **Capture**: Accumulates Float32 samples into 960-sample (20ms) Int16 frames
+- **Playback**: Ring buffer capped at 200ms (9600 samples at 48 kHz)
+
+## Identity System
+
+### Overview
+
+Your identity is a 32-byte cryptographic seed that derives:
+
+- **Ed25519 signing key** -- authenticates handshake messages
+- **X25519 key agreement key** -- derives shared session encryption keys
+- **Fingerprint** -- SHA-256 of the public key, truncated to 16 bytes, displayed as `xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx`
+- **Identicon** -- deterministic visual avatar generated from the fingerprint
+
+### Seed Sources
+
+| Source | Description |
+|--------|-------------|
+| Auto-generated | Created on first run, stored in `~/.wzp/identity` (desktop/CLI) or app storage (Android) |
+| `--seed <hex>` | 64-character hex string (CLI) |
+| `--mnemonic <words>` | 24-word BIP39 mnemonic (CLI) |
+| Copy Key / Restore Key | Hex backup/restore (Android settings) |
+
+### BIP39 Mnemonic Backup
+
+The 32-byte seed can be represented as a 24-word BIP39 mnemonic for human-readable backup. The same mnemonic produces the same identity on any platform or device.
+
+### featherChat Compatibility
+
+The identity derivation uses the same HKDF scheme as featherChat (Warzone messenger). The same seed produces the same fingerprint in both systems, allowing a unified identity across messaging and calling.
+
+### Trust on First Use (TOFU)
+
+Clients remember the fingerprints of relays and peers they connect to. On subsequent connections, if a fingerprint changes, the client warns the user. This protects against man-in-the-middle attacks but requires manual verification on first contact.
+
+## Quality Profiles Explained
+
+### When to Use Each Profile
+
+| Profile | Total Bandwidth | Best For | Trade-offs |
+|---------|----------------|----------|------------|
+| **Studio 64k** | 70.4 kbps | LAN calls, music, podcasting | Highest quality, needs good network |
+| **Studio 48k** | 52.8 kbps | Good WiFi, wired connections | Near-studio quality |
+| **Studio 32k** | 35.2 kbps | Reliable WiFi, LTE | Very good quality with lower bandwidth |
+| **Auto** | Adaptive | Most users | Automatically switches based on network conditions |
+| **Opus 24k** | 28.8 kbps | General use, moderate networks | Good speech quality, reasonable bandwidth |
+| **Opus 6k** | 9.0 kbps | 3G networks, congested WiFi | Intelligible speech, some artifacts |
+| **Codec2 3.2k** | 4.8 kbps | Poor connections | Robotic but intelligible, narrowband |
+| **Codec2 1.2k** | 2.4 kbps | Satellite links, extreme loss | Minimal intelligibility, last resort |
+
+### Auto Mode
+
+Auto mode starts at the **Good (Opus 24k)** profile and adapts based on observed network quality:
+
+- **Downgrade** -- 3 consecutive bad quality reports (2 on cellular) trigger a step down
+- **Upgrade** -- 10 consecutive good quality reports trigger a step up (one tier at a time)
+- **Network handoff** -- switching from WiFi to cellular triggers a preemptive one-tier downgrade plus a 10-second FEC boost
+
+Auto mode uses three tiers (Good, Degraded, Catastrophic). It does not use the Studio profiles, which must be selected manually.
+
+### Manual Override
+
+When you select a specific profile (not Auto), adaptive switching is disabled. The encoder stays at the selected profile regardless of network conditions. This is useful when you know your network quality and want consistent encoding, or when you want to force a specific bitrate.
+
+Note: The decoder always accepts all codecs. A manual quality selection only affects what you send, not what you receive.
+
+## Direct 1:1 Calling (Desktop + Android)
+
+In addition to room-mode group calls, you can place direct calls to a specific peer by fingerprint. Direct calls bypass room state entirely — the relay is used purely as a signaling gateway and for media relay. There is no need for the callee to join a room beforehand; they just need to be registered with the same signal hub.
+
+### UI elements in the direct-call panel
+
+- **Place call field** — paste a fingerprint (the long hex string you see under your own identity) and click Call. The callee sees a ringing UI.
+- **Recent contacts row** — a horizontal strip of chips showing your most recently called/receiving peers. Click a chip to re-dial. Aliases are shown if the peer has one, otherwise a short fingerprint prefix.
+- **Call history list** — every direct call you've placed, received, or missed, with direction indicator (↗ Outgoing, ↙ Incoming, ✗ Missed), the peer's alias (if known) or fingerprint prefix, and a timestamp. Click an entry to re-dial.
+- **Deregister button** — drops your signal-hub registration without quitting the app. Useful when switching identities (e.g. testing with two accounts on one machine) or when you want to explicitly appear offline to peers.
+- **Clear history button** — wipes the call history store. Does not affect current calls.
+
+### Live updates
+
+The call history updates in real time across all views via Tauri events (`history-changed`). Placing, answering, or missing a call immediately refreshes the history list and the recent contacts row — no manual refresh needed.
+
+### Default room
+
+On first launch, the room name in the room-mode panel defaults to `general` (changed from the prior `android` default so the desktop and Android clients don't silently talk past each other). You can still change it to any room name, and the last-used room is remembered across launches.
+
+### Random alias
+
+New installations derive a human-friendly alias from your identity seed — something like `silent-forest-41` or `bold-river-07`. It's deterministic, so reinstalling without changing your seed gives you the same alias. The alias is shown alongside your fingerprint in the header and is what peers see in their call history when they receive your call.
+
+You can override the alias in Settings → Identity if you want a specific name.
+
+## Windows AEC Variants
+
+The Windows desktop build ships in two variants for echo cancellation, depending on which backend you want to exercise. Both are `wzp-desktop.exe` binaries — only the internal audio backend differs.
+
+| Build | File | Capture backend | AEC | When to use |
+|---|---|---|---|---|
+| **noAEC baseline** | `wzp-desktop-noAEC.exe` | CPAL (WASAPI shared mode) | None | Headphone-only use, or for A/B comparison against the AEC build |
+| **Communications AEC** | `wzp-desktop.exe` | Direct WASAPI with `AudioCategory_Communications` | **Yes** — Windows routes the capture stream through the driver's communications APO chain (AEC + noise suppression + automatic gain control) | Any speaker-mode call, laptop built-in speakers, anywhere echo is audible |
+
+**Quality caveat**: the communications AEC operates at the OS level and its algorithm depends on the audio driver's installed APO chain. On modern consumer laptops with Intel Smart Sound, Dolby, recent Realtek, or Windows 11 Voice Clarity, the quality is excellent (effectively matching what Teams/Zoom deliver). On generic class-compliant USB microphones or older drivers, the communications APO may not be present at all — in that case the build behaves identically to the noAEC baseline.
+
+If you hear echo on the AEC build, try these in order before escalating:
+
+1. **Check which capture device is selected as "Default Device - Communications"** in Windows Sound Settings → Recording tab. Right-click any device to set it. The AEC build opens the device marked as `eCommunications`, not `eConsole`, so changing the default-communications device changes what we capture from.
+2. **Verify the driver exposes a communications APO**. Sound Settings → Recording → your mic → Properties → Advanced → look for an "Enhancements" or "Signal Enhancements" tab. If it's absent, the driver has no APOs and the AEC build effectively has no AEC.
+3. **Try the classic Voice Capture DSP build** when it ships (tracked as task #26). That uses Microsoft's bundled software AEC (`CLSID_CWMAudioAEC`) which works on every Windows machine regardless of driver.
+
+### Installing the Windows builds
+
+1. Windows 10: install the [WebView2 Runtime Evergreen Bootstrapper](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) first. Windows 11 has it pre-installed.
+2. Copy `wzp-desktop.exe` (or `wzp-desktop-noAEC.exe`) to any directory and double-click. No installer needed.
+3. First launch creates the config + identity store at `%APPDATA%\com.wzp.phone\`.

docs/incident-tauri-android-init-tcb.md

@@ -0,0 +1,431 @@
+# Incident report — Tauri Android `__init_tcb+4` SIGSEGV
+
+**Status:** Blocked. Reproducible crash with a known trigger at the cc::Build /
+rustc-link-lib layer that we cannot yet explain. Writing this report to hand
+off for external help.
+
+**Project:** WarzonePhone (Rust + Tauri 2.x Mobile) Android rewrite
+**Branch:** `feat/desktop-audio-rewrite`
+**Target phone:** Pixel 6 (`oriole`), Android 16 (`BP3A.250905.014`), arm64-v8a
+**Date range of investigation:** 2026-04-09 (one working session, ~27 builds)
+
+---
+
+## One-paragraph summary
+
+We're porting the existing CPAL-backed desktop Tauri app (`desktop/src-tauri`)
+to Tauri Mobile Android so the same Rust + Tauri + WebView codebase runs on
+both platforms. The Android `.apk` launches, renders the home screen, and
+registers on a relay for signal-only builds (no audio backend). The moment
+we add **any** `cc::Build::new().cpp(true).cpp_link_stdlib("c++_shared")`
+call to `build.rs` — even with a 6-line cpp file that just returns 42 and is
+never called from Rust — the built `.so` crashes at launch inside
+`__init_tcb(bionic_tcb*, pthread_internal_t*)+4` via `pthread_create` via
+`std::thread::spawn` via `tao::ndk_glue::create` via
+`Java_com_wzp_desktop_WryActivity_create`, before our Rust entry point has
+a chance to run. The exact same NDK, exact same Rust toolchain, exact same
+Docker image is used by the legacy `wzp-android` crate (via `cargo-ndk`)
+which compiles Oboe and runs fine on the same phone.
+
+---
+
+## Environment
+
+**Docker build image:** `wzp-android-builder` (Dockerfile at
+`scripts/Dockerfile.android-builder`)
+
+- Base: `debian:bookworm`
+- JDK 17
+- Android SDK:
+  - cmdline-tools latest
+  - `platforms;android-34`, `platforms;android-36`
+  - `build-tools;34.0.0`, `build-tools;35.0.0`
+  - `ndk;26.1.10909125` (last stable before scudo/MTE crash on NDK r27+)
+  - `platform-tools`
+- Node.js 20 LTS
+- Rust stable `1.94.1 (e408947bf 2026-03-25)`
+- Rust android targets: `aarch64-linux-android`, `armv7-linux-androideabi`,
+  `i686-linux-android`, `x86_64-linux-android`
+- `cargo-ndk` + `cargo tauri-cli 2.10.1` (latest 2.x)
+
+**Host:** Docker on `SepehrHomeserverdk` (remote build server).
+
+**Phone:** Pixel 6, Android 16, kernel 6.1.134-android14-11, on the same LAN
+as the build machine and a local `wzp-relay` binary.
+
+**Tauri crate:** `desktop/src-tauri/` in the workspace at the root of the
+repo. Depends on `tauri = "2"`, `tauri-plugin-shell = "2"`, `tokio`, `rustls`,
+`wzp-proto`, `wzp-codec`, `wzp-fec`, `wzp-crypto`, `wzp-transport`, and (on
+non-Android only) `wzp-client` with `features = ["audio", "vpio"]`. The
+crate's `[lib]` section is:
+
+```toml
+[lib]
+name = "wzp_desktop_lib"
+crate-type = ["staticlib", "cdylib", "rlib"]
+```
+
+The crate produces `libwzp_desktop_lib.so` which is `System.loadLibrary`'d by
+Tauri's generated `WryActivity.onCreate` via JNI.
+
+---
+
+## The crash
+
+Every failing build produces the same stack at launch, same pc offsets:
+
+```
+signal 11 (SIGSEGV), code 2 (SEGV_ACCERR), fault addr 0x00000072XXXXXX00f (write)
+
+#00 pc 000000000130cc74 libwzp_desktop_lib.so (__init_tcb(bionic_tcb*, pthread_internal_t*)+4)
+#01 pc 0000000001331cf0 libwzp_desktop_lib.so (pthread_create+360)
+#02 pc 00000000012bee04 libwzp_desktop_lib.so (std::sys::thread::unix::Thread::new::h87be8e9feeaaaf84+184)
+#03 pc 0000000000e37f5c libwzp_desktop_lib.so (std::thread::lifecycle::spawn_unchecked::h941f828f9a95150d+1504)
+#04 pc 0000000000e461e8 libwzp_desktop_lib.so (std::thread::builder::Builder::spawn_unchecked::hec5f087680cb0248+112)
+#05 pc 0000000000e441c8 libwzp_desktop_lib.so (std::thread::functions::spawn::ha3d3fbf2d9fe53e3+108)
+#06 pc ...             libwzp_desktop_lib.so (tao::platform_impl::platform::ndk_glue::create::h254c68662718841a+1792)
+#07 pc ...             libwzp_desktop_lib.so (Java_com_wzp_desktop_WryActivity_create+76)
+```
+
+The offsets are **byte-identical across every failing build**, even when the
+cpp content changes drastically (cf. `cpp_smoke.cpp` at 6 lines, 20 lines,
+200+ Oboe source files). We believe this is because cargo caches the Rust
+compilation unit and only the build-script artifacts differ, and the final
+link produces the same layout.
+
+`__init_tcb` is defined locally inside our `.so` with C++ mangling:
+
+```
+_Z10__init_tcbP10bionic_tcbP18pthread_internal_t
+```
+
+It originates from bionic's `pthread_create.cpp`, which got pulled in
+statically from the NDK's `sysroot/usr/lib/aarch64-linux-android/libc.a`.
+Both failing and known-good (legacy `wzp_android.so`) builds contain this
+same static symbol — the presence of the symbol is not the problem.
+
+Fault address `0x72XXXXXX00f` with code `SEGV_ACCERR` (access permission
+error, write). Aligned to `+4` inside `__init_tcb`, which is typically a
+store into the passed-in `bionic_tcb*`. The pointer is either NULL-ish or
+pointing into read-only memory.
+
+---
+
+## Bisection (the important part)
+
+We started from a known-good commit (`5309938`) where the Tauri Android app
+launches, registers on a relay, and behaves identically to the desktop app
+modulo audio. Then we added features **one variable at a time**:
+
+| Step | Commit | Change vs previous | Result |
+|---|---|---|---|
+| Baseline | `5309938` | — | ✅ launches, renders home, registers on relay |
+| **A** | `f96d7ce` | Add `cc = "1"` build-dep + compile trivial `cpp/hello.c` via `cc::Build` (C, not C++). Static lib never linked in. | ✅ |
+| **B** | `ae4f366` | Add `wzp-client` Android dep with `default-features = false` (no CPAL, no VPIO). No new imports. | ✅ |
+| **C** | `19fd3dd` | Un-cfg-gate `mod engine;` in `lib.rs` so `engine.rs` compiles on Android. `CallEngine::start()` has an Android stub returning an error. | ✅ |
+| **D** | `a852cad` | Compile `cpp/getauxval_fix.c` (legacy wzp-android shim). Still pure C. | ✅ |
+| **E** | `4250f1b` | **Compile full Oboe C++ bridge** (200+ source files from `google/oboe@1.8.1`). `cc::Build::new().cpp(true).std("c++17").cpp_link_stdlib(Some("c++_shared"))` + `-llog` + `-lOpenSLES` link directives. Nothing called from Rust yet — the `extern "C"` bridge functions are exported but never referenced from the Rust side. | ❌ **crash** |
+| E.4 | `aa240c6` | **Only change:** replace the entire Oboe compile with ONE tiny `cpp_smoke.cpp` file: `extern "C" int wzp_cpp_smoke(void) { std::lock_guard<std::mutex> lk(m); std::thread t([](){...}); t.join(); return g.load(); }`. Still `cpp(true) + cpp_link_stdlib("c++_shared")`. Drop `-llog`/`-lOpenSLES`. | ❌ **same crash, same offsets** |
+| E.2 | `0224ce6` | Shrink `cpp_smoke.cpp` further: just `std::atomic<int>` + `fetch_add`, no mutex, no thread, no includes beyond `<atomic>`. | ❌ **same crash, same offsets** |
+| E.1 | `0d74366` | **Absolute minimum:** `cpp_smoke.cpp` = `extern "C" int wzp_cpp_hello(void){return 42;}`. NO `#include`. NO STL. Just a function. Still compiled with `cpp(true) + cpp_link_stdlib("c++_shared")`. | ❌ **same crash, same offsets** |
+
+### Additional confirming observations
+
+1. **The cpp code is dead-stripped.** `llvm-nm -a libwzp_desktop_lib.so` shows
+   zero matches for `wzp_cpp_hello`, `wzp_cpp_smoke`, or any Oboe symbol in
+   builds E through E.1. The static archive (`libwzp_cpp_smoke.a` /
+   `liboboe_bridge.a`) exists on disk under
+   `target/aarch64-linux-android/debug/build/wzp-desktop-*/out/`, but because
+   nothing in Rust ever references the exported C function, the final linker
+   drops it.
+
+2. **`build.rs` link directives are the real delta.** `cc::Build::new()
+   .cpp(true).cpp_link_stdlib(Some("c++_shared"))` emits a
+   `cargo:rustc-link-lib=c++_shared` directive that adds a `NEEDED` entry for
+   `libc++_shared.so` to the final `.so`'s dynamic table. `readelf -d` on
+   the crashing `.so` shows:
+
+   ```
+   NEEDED       Shared library: [libc++_shared.so]
+   NEEDED       Shared library: [liblog.so]      (only in full Oboe build)
+   NEEDED       Shared library: [libOpenSLES.so] (only in full Oboe build)
+   ```
+
+   The working baseline `.so` has no `NEEDED` entries beyond libc/liblog.
+
+3. **Linker version doesn't matter.** We tried forcing
+   `aarch64-linux-android26-clang` as the linker (API 26 has proper dynamic
+   bindings to libc.so's runtime `pthread_create`/`__init_tcb`) via three
+   different mechanisms:
+   - `CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER` env var in `docker run`
+   - `.cargo/config.toml` workspace-level linker override
+   - **Binary replacement inside the image**: `mv
+     aarch64-linux-android24-clang .orig` and replace with a shell script
+     that `exec`s `aarch64-linux-android26-clang`. Verified by calling
+     `--version` which prints `Target: aarch64-unknown-linux-android26`.
+
+   All three made no difference. The `__init_tcb` symbol is pulled statically
+   from the **same** `libc.a` regardless of which clang wrapper is used — the
+   NDK ships ONE `libc.a` at
+   `sysroot/usr/lib/aarch64-linux-android/libc.a` shared across all API
+   levels. Only the per-API `libc.so` symlinks change (and we're linked
+   statically, not dynamically, against libc).
+
+4. **Legacy `wzp-android` crate works on the same phone, same image.** Run
+   in the exact same Docker container, the legacy Kotlin app's JNI library
+   (`crates/wzp-android` built via `cargo ndk`) compiles a subset of the
+   same Oboe code, produces a `.so` that has the same static
+   `_Z10__init_tcbP...` + `pthread_create` + `pthread_create.cpp` symbols,
+   and launches cleanly on the Pixel 6. Key differences between the two
+   build paths:
+
+   | | `wzp-android` (works) | `wzp-desktop` Tauri (crashes) |
+   |---|---|---|
+   | Build driver | `cargo ndk -t arm64-v8a build --release -p wzp-android` | `cargo tauri android build --debug --target aarch64 --apk` |
+   | Profile | release | debug (release crashes identically) |
+   | Linker | `aarch64-linux-android26-clang` (via `.cargo/config.toml` which cargo-ndk honors) | `aarch64-linux-android24-clang` (tauri-cli hardcodes and ignores config; the shim redirect makes no difference) |
+   | crate-type | `["cdylib", "rlib"]` | `["staticlib", "cdylib", "rlib"]` |
+   | JNI entrypoint | direct Kotlin `System.loadLibrary` + our own `native fun` declarations; first `pthread_create` runs later from the tokio runtime inside a command | `WryActivity.onCreate` via Tauri's generated Java glue; first `pthread_create` runs **inside the JNI call** via `tao::ndk_glue::create` |
+   | Other heavy deps | tokio, wzp-{proto,codec,fec,crypto,transport} | tokio, tauri, tauri-runtime-wry, tao, wry, webview2-com, soup3, webkit2gtk (all platform-specific ones cfg-gated out of android), and also all of the above |
+   | Binary size | `libwzp_android.so` ≈ 14 MB (release) | `libwzp_desktop_lib.so` ≈ 160 MB (debug), 16 MB (release) |
+
+5. **The crash happens in the JNI-callback thread during `onCreate`.** Frame
+   #06 `tao::platform_impl::platform::ndk_glue::create+1792` is tao's Android
+   event-loop bootstrap, which Tauri calls from inside
+   `Java_com_wzp_desktop_WryActivity_create` in response to the Java-side
+   activity lifecycle. This means the thread spawn is happening while the
+   Java VM still holds the native onCreate call, before `onCreate` has
+   returned to the Android runtime. Legacy `wzp-android` never spawns a
+   thread from an onCreate JNI call — it spawns threads only from
+   `nativeSignalConnect`/similar commands invoked later from Kotlin button
+   clicks, after the activity is fully initialised.
+
+---
+
+## Current suspect
+
+One of the two items below, probably (2):
+
+1. **The `.cpp(true)` mode in cc-rs changes something invisible in the link
+   pipeline** (for example, emitting a different `-x` flag to clang, or
+   changing linker driver selection). We have not yet verified this by
+   diffing the actual rustc linker invocation between a working and a
+   crashing build with `--verbose` + `-Clink-arg=-Wl,-t`.
+
+2. **Adding `libc++_shared.so` as a NEEDED entry causes Android's dynamic
+   linker to load libc++_shared.so before our `.so`'s init runs, and
+   something in libc++_shared's `.init_array` interacts badly with
+   tao::ndk_glue's `pthread_create` call from inside the JNI onCreate
+   window**. The legacy crate doesn't hit this because (a) it has no
+   NEEDED libc++_shared when built without Oboe, and (b) even when it does
+   build Oboe, its thread spawns happen outside the onCreate JNI call so
+   whatever libc state is wrong at that moment is already stabilised.
+
+We have not yet confirmed (2) with the obvious A/B test: keep `cpp_smoke.cpp`
+but drop `.cpp_link_stdlib(Some("c++_shared"))` (and drop any manual
+`cargo:rustc-link-lib=c++_shared`) so the NEEDED entry disappears but the
+rest of the pipeline stays identical. That's the next experiment we were
+going to run, but the user reasonably asked for this report first.
+
+---
+
+## What we've ruled out
+
+- **NDK API level** — forcing API-26 linker via three independent mechanisms
+  made zero difference.
+- **Build profile** — release (`0x6b8000` offset, 21 MB unsigned APK) and
+  debug (same 193 MB APK, same crash offsets) both crash identically.
+- **Oboe specifically** — replacing the Oboe compile with 6 lines of C++
+  that does nothing still reproduces the crash.
+- **cpp code being executed at runtime** — dead-stripped, not in the final
+  `.so` at all per `nm -a`.
+- **minSdk in build.gradle** — bumped from 24 to 26, no effect.
+- **libdl.a stub issue** — ruled out via logcat (`libdl.a is a stub --- use
+  libdl.so instead` was only surfacing from our own `dlsym` shim that we
+  subsequently deleted).
+- **`pthread_create` interposition via `-Wl,--wrap=pthread_create`** — tried
+  and reverted; the wrap target still resolved to the broken static stub.
+- **Keystore / signing** — debug signing with persistent `~/.android/
+  debug.keystore` works fine; no signature mismatch issues.
+
+---
+
+## The files involved
+
+### `desktop/src-tauri/build.rs` (current state, E.1)
+
+```rust
+use std::path::PathBuf;
+use std::process::Command;
+
+fn main() {
+    // Embedded git hash
+    let git_hash = Command::new("git")
+        .args(["rev-parse", "--short", "HEAD"])
+        .output()
+        .ok()
+        .filter(|o| o.status.success())
+        .and_then(|o| String::from_utf8(o.stdout).ok())
+        .map(|s| s.trim().to_string())
+        .unwrap_or_else(|| "unknown".into());
+    println!("cargo:rustc-env=WZP_GIT_HASH={git_hash}");
+    println!("cargo:rerun-if-changed=../../.git/HEAD");
+    println!("cargo:rerun-if-changed=../../.git/refs/heads");
+
+    let target = std::env::var("TARGET").unwrap_or_default();
+    if target.contains("android") {
+        // Step A: plain C sanity file
+        println!("cargo:rerun-if-changed=cpp/hello.c");
+        cc::Build::new().file("cpp/hello.c").compile("wzp_hello");
+
+        // Step D: legacy getauxval shim
+        println!("cargo:rerun-if-changed=cpp/getauxval_fix.c");
+        cc::Build::new().file("cpp/getauxval_fix.c").compile("getauxval_fix");
+
+        // Step E.1: minimal C++ smoke — THIS STEP BRINGS BACK THE CRASH
+        println!("cargo:rerun-if-changed=cpp/cpp_smoke.cpp");
+        cc::Build::new()
+            .cpp(true)
+            .std("c++17")
+            .cpp_link_stdlib(Some("c++_shared"))
+            .file("cpp/cpp_smoke.cpp")
+            .compile("wzp_cpp_smoke");
+
+        // Copy libc++_shared.so into gen/android jniLibs so the runtime
+        // linker can find it when the NEEDED entry fires.
+        if let Ok(ndk) = std::env::var("ANDROID_NDK_HOME").or_else(|_| std::env::var("NDK_HOME")) {
+            let triple = "aarch64-linux-android";
+            let abi = "arm64-v8a";
+            let lib_dir = format!(
+                "{ndk}/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/{triple}"
+            );
+            println!("cargo:rustc-link-search=native={lib_dir}");
+            let shared_so = format!("{lib_dir}/libc++_shared.so");
+            if std::path::Path::new(&shared_so).exists() {
+                let manifest = std::env::var("CARGO_MANIFEST_DIR").unwrap_or_default();
+                let jni_dir = format!("{manifest}/gen/android/app/src/main/jniLibs/{abi}");
+                if std::fs::create_dir_all(&jni_dir).is_ok() {
+                    let _ = std::fs::copy(&shared_so, format!("{jni_dir}/libc++_shared.so"));
+                }
+            }
+        }
+    }
+
+    tauri_build::build()
+}
+```
+
+### `desktop/src-tauri/cpp/cpp_smoke.cpp` (E.1)
+
+```cpp
+extern "C" int wzp_cpp_hello(void) {
+    return 42;
+}
+```
+
+### `desktop/src-tauri/Cargo.toml` (relevant excerpts)
+
+```toml
+[package]
+name = "wzp-desktop"
+version = "0.1.0"
+edition = "2024"
+
+[lib]
+name = "wzp_desktop_lib"
+crate-type = ["staticlib", "cdylib", "rlib"]
+
+[[bin]]
+name = "wzp-desktop"
+path = "src/main.rs"
+
+[build-dependencies]
+tauri-build = { version = "2", features = [] }
+cc = "1"
+
+[dependencies]
+tauri = { version = "2", features = [] }
+tauri-plugin-shell = "2"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+tokio = { version = "1", features = ["full"] }
+tracing = "0.1"
+tracing-subscriber = "0.3"
+anyhow = "1"
+rustls = { version = "0.23", default-features = false, features = ["ring", "std"] }
+
+wzp-proto = { path = "../../crates/wzp-proto" }
+wzp-codec = { path = "../../crates/wzp-codec" }
+wzp-fec = { path = "../../crates/wzp-fec" }
+wzp-crypto = { path = "../../crates/wzp-crypto" }
+wzp-transport = { path = "../../crates/wzp-transport" }
+
+[target.'cfg(not(target_os = "android"))'.dependencies]
+wzp-client = { path = "../../crates/wzp-client", features = ["audio", "vpio"] }
+
+[target.'cfg(target_os = "android")'.dependencies]
+wzp-client = { path = "../../crates/wzp-client", default-features = false }
+```
+
+---
+
+## Reproduction
+
+A fresh clone on a Linux x86_64 host with:
+
+```bash
+git clone ssh://git@git.manko.yoga:222/manawenuz/wz-phone.git
+cd wz-phone
+git checkout feat/desktop-audio-rewrite
+git reset --hard 0d74366   # <-- step E.1, smallest crashing commit
+
+# Need: Android NDK r26.1.10909125, JDK 17, Node 20, Rust stable, cargo tauri 2.x
+scripts/prep-linux-mint.sh    # installs all the above into /opt/android-sdk etc.
+
+cd desktop
+npm install
+cd src-tauri
+cargo tauri android build --debug --target aarch64 --apk
+adb install -r gen/android/app/build/outputs/apk/universal/debug/app-universal-debug.apk
+adb logcat -c && adb shell am start -n com.wzp.desktop/.MainActivity
+adb logcat | grep -E "F DEBUG|__init_tcb|pthread_create"
+```
+
+Expected result: SIGSEGV at `__init_tcb+4` within ~500 ms of launch.
+
+Reverting `cpp/cpp_smoke.cpp` + the `cc::Build` call for it in `build.rs`
+(one git command: `git revert 0d74366 aa240c6 0224ce6 a852cad`) restores a
+working build. Keeping the C sanity compile (`hello.c`, `getauxval_fix.c`)
+is fine — only the `.cpp(true) + .cpp_link_stdlib("c++_shared")` combination
+triggers the regression.
+
+---
+
+## What we'd like help with
+
+1. **Is our suspect #2 actually the mechanism?** Is there a known issue
+   where a Tauri/tao android cdylib crashes on load when it has a
+   `libc++_shared.so` NEEDED entry and tries to spawn a thread from inside
+   an onCreate JNI call?
+
+2. **What's the correct way to link Oboe (or any C++ Android audio
+   library) into a `cargo tauri android build` cdylib** without hitting
+   this? Is there a known-good combination of cc-rs flags / linker
+   arguments / cargo config?
+
+3. **Is there a way to force `cargo tauri` to use the same linker setup
+   as `cargo ndk`**, which reliably produces working Oboe-linked .so
+   files from the exact same workspace? We've tried env var override,
+   `.cargo/config.toml`, and image-level binary replacement — cargo
+   tauri ignores all three and keeps using
+   `aarch64-linux-android24-clang`.
+
+4. **Is there a way to defer `tao::ndk_glue::create`'s thread spawn to
+   after `onCreate` returns** so that whatever bionic state `__init_tcb`
+   depends on is ready?
+
+5. **Lastly** — is there a fundamentally different approach we should
+   take (e.g., use the `oboe` Rust crate from crates.io instead of a
+   hand-rolled C++ bridge, use Android's AAudio directly via the `ndk`
+   crate's aaudio bindings, or even abandon the C++ audio path and
+   implement mic/speaker via JNI into Java `AudioRecord`/`AudioTrack`)?

scripts/Dockerfile.android-builder

@@ -1,11 +1,16 @@
 # =============================================================================
 # WZ Phone — Android build environment (Debian 12 / Bookworm)
 #
-# Matches the bare-metal build-android.sh environment:
+# Supports both:
+#   1. Legacy Kotlin+JNI Android app (via cargo-ndk + gradle)
+#   2. Tauri 2.x Mobile Android app (via tauri-cli + Node/npm)
+#
+# Toolchain:
 #   - Debian 12 (cmake 3.25, no Android cross-compilation bugs)
 #   - JDK 17 (Gradle 8.5 + AGP 8.2.0 compatible)
 #   - NDK 26.1 (last stable before scudo/MTE crash on NDK 27+)
-#   - Rust stable with aarch64-linux-android target + cargo-ndk
+#   - Node.js 20 LTS (for Tauri frontend build)
+#   - Rust stable with all 4 Android targets + cargo-ndk + tauri-cli 2.x
 #
 # Build:  docker build -t wzp-android-builder -f Dockerfile.android-builder .
 # =============================================================================
@@ -13,6 +18,11 @@ FROM debian:bookworm
 
 ARG NDK_VERSION=26.1.10909125
 ARG ANDROID_API=34
+# Tauri 2.x mobile targets compileSdk 36 + build-tools 35 by default. Install
+# both 34 (legacy Kotlin app) and 35/36 (Tauri mobile) so the same image works
+# for both pipelines.
+ARG ANDROID_API_TAURI=36
+ARG BUILD_TOOLS_TAURI=35.0.0
 
 ENV DEBIAN_FRONTEND=noninteractive \
     ANDROID_HOME=/opt/android-sdk \
@@ -35,8 +45,17 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
         openjdk-17-jdk-headless \
         ca-certificates \
         libasound2-dev \
+        file \
+        xz-utils \
     && rm -rf /var/lib/apt/lists/*
 
+# ── Node.js 20 LTS (required by Tauri for frontend build) ────────────────────
+RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y --no-install-recommends nodejs \
+    && rm -rf /var/lib/apt/lists/* \
+    && node --version \
+    && npm --version
+
 # ── Android SDK + NDK 26.1 ──────────────────────────────────────────────────
 RUN mkdir -p $ANDROID_HOME/cmdline-tools \
     && cd /tmp \
@@ -49,10 +68,36 @@ RUN yes | $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --licenses > /dev/nu
     && $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --install \
         "platforms;android-${ANDROID_API}" \
         "build-tools;${ANDROID_API}.0.0" \
+        "platforms;android-${ANDROID_API_TAURI}" \
+        "build-tools;${BUILD_TOOLS_TAURI}" \
         "ndk;${NDK_VERSION}" \
         "platform-tools" \
         2>&1 | grep -v '^\[' > /dev/null
 
+# Work around the API-24 libc.a stub in the NDK. Any C++ static lib we
+# link into libwzp_desktop_lib.so (e.g. the Oboe audio bridge) pulls in
+# bionic's static pthread_create from API-24 libc.a via libc++_shared,
+# and that pthread_create crashes at __init_tcb+4 when called from a
+# .so loaded via dlopen (the static stub expects libc init state that
+# only exists for main executables). API-26 has the proper runtime
+# bindings. Tauri-cli hard-codes aarch64-linux-android24-clang as the
+# linker and ignores .cargo/config.toml overrides, so the only sure
+# fix is to replace the NDK's ${abi}24-clang binary itself with a
+# shim that exec()s the ${abi}26-clang equivalent. Applies to all four
+# ABIs × {clang, clang++}. The legacy wzp-android crate works without
+# this because cargo-ndk honours a crate-level linker override; the
+# shim is the minimal targeted fix for the cargo-tauri build path.
+# Added as Option 3 for the incremental Step E regression (commit 4250f1b).
+RUN set -eux; \
+    BIN=$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin; \
+    for abi in aarch64-linux-android armv7a-linux-androideabi i686-linux-android x86_64-linux-android; do \
+        for suffix in clang clang++; do \
+            mv "$BIN/${abi}24-${suffix}" "$BIN/${abi}24-${suffix}.orig"; \
+            printf '#!/bin/sh\nexec "%s/%s26-%s" "$@"\n' "$BIN" "$abi" "$suffix" > "$BIN/${abi}24-${suffix}"; \
+            chmod +x "$BIN/${abi}24-${suffix}"; \
+        done; \
+    done
+
 # Make SDK world-readable so builder user can access it
 RUN chmod -R a+rX $ANDROID_HOME
 
@@ -64,12 +109,22 @@ USER builder
 WORKDIR /home/builder
 
 # ── Rust toolchain ───────────────────────────────────────────────────────────
+# Install all 4 Android targets (Tauri Mobile builds for all ABIs by default;
+# cargo-ndk legacy path only needs arm64-v8a — both workflows supported).
 RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
         | sh -s -- -y --default-toolchain stable \
     && . $HOME/.cargo/env \
-    && rustup target add aarch64-linux-android \
-    && cargo install cargo-ndk
+    && rustup target add \
+        aarch64-linux-android \
+        armv7-linux-androideabi \
+        i686-linux-android \
+        x86_64-linux-android \
+    && cargo install cargo-ndk \
+    && cargo install tauri-cli --version "^2.0" --locked
 
 ENV PATH="/home/builder/.cargo/bin:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$JAVA_HOME/bin:$PATH"
 
+# NDK_HOME is the env var tauri-cli checks (in addition to ANDROID_NDK_HOME)
+ENV NDK_HOME=$ANDROID_NDK_HOME
+
 WORKDIR /build/source

scripts/build-and-notify.sh

@@ -17,12 +17,13 @@ LOCAL_OUTPUT="target/android-apk"
 SSH_OPTS="-o ConnectTimeout=15 -o ServerAliveInterval=15 -o ServerAliveCountMax=4 -o LogLevel=ERROR"
 
 REBUILD_RUST=0
-DO_PULL=0
+DO_PULL=1
 DO_INSTALL=0
 for arg in "$@"; do
     case "$arg" in
         --rust) REBUILD_RUST=1 ;;
         --pull) DO_PULL=1 ;;
+        --no-pull) DO_PULL=0 ;;
         --install) DO_INSTALL=1 ;;
     esac
 done
@@ -50,8 +51,11 @@ trap 'notify "WZP Android build FAILED! Check /tmp/wzp-build.log"' ERR
 if [ "$DO_PULL" = "1" ]; then
     echo ">>> Pulling latest..."
     cd "$BASE_DIR/data/source"
-    git checkout -- . 2>/dev/null || true
-    git pull origin feat/android-voip-client 2>&1 | tail -3
+    git reset --hard HEAD 2>/dev/null || true
+    git clean -fd 2>/dev/null || true
+    git gc --prune=now 2>/dev/null || true
+    git fetch origin feat/android-voip-client 2>&1 | tail -3
+    git reset --hard origin/feat/android-voip-client 2>/dev/null || true
 fi
 
 # Clean Rust if requested
@@ -68,7 +72,8 @@ find "$BASE_DIR/data/source" "$BASE_DIR/data/cache" \
 # Clean jniLibs
 rm -rf "$BASE_DIR/data/source/android/app/src/main/jniLibs/arm64-v8a"
 
-notify "WZP build started..."
+GIT_HASH=$(cd $BASE_DIR/data/source && git rev-parse --short HEAD 2>/dev/null || echo unknown)
+notify "WZP Android build started [$GIT_HASH]..."
 
 echo ">>> Building in Docker..."
 docker run --rm --user 1000:1000 \
@@ -101,7 +106,7 @@ ls -lh android/app/src/main/jniLibs/arm64-v8a/
 
 echo ">>> APK build..."
 cd android && chmod +x gradlew
-./gradlew clean assembleDebug --no-daemon --warning-mode=none 2>&1 | tail -3
+./gradlew clean assembleDebug --no-daemon --warning-mode=none 2>&1 | tail -50
 echo "APK_BUILT"
 '
 
@@ -112,7 +117,7 @@ APK=$(find "$BASE_DIR/data/source/android" -name "app-debug*.apk" -path "*/outpu
 if [ -n "$APK" ]; then
     URL=$(curl -s -F "file=@$APK" -H "Authorization: $rusty_auth_token" "$rusty_address")
     echo "UPLOAD_URL=$URL"
-    notify "WZP build done! APK: $URL"
+    notify "WZP Android [$GIT_HASH] done! APK: $URL"
     echo ">>> Done! APK at: $URL"
 else
     notify "WZP build FAILED - no APK"

scripts/build-linux-docker.sh

@@ -17,12 +17,13 @@ NTFY_TOPIC="https://ntfy.sh/wzp"
 LOCAL_OUTPUT="target/linux-x86_64"
 SSH_OPTS="-o ConnectTimeout=15 -o ServerAliveInterval=15 -o ServerAliveCountMax=4 -o LogLevel=ERROR"
 
-DO_PULL=0
+DO_PULL=1
 DO_CLEAN=0
 DO_INSTALL=0
 for arg in "$@"; do
     case "$arg" in
         --pull) DO_PULL=1 ;;
+        --no-pull) DO_PULL=0 ;;
         --clean) DO_CLEAN=1 ;;
         --install) DO_INSTALL=1 ;;
     esac
@@ -51,8 +52,11 @@ trap 'notify "WZP Linux build FAILED! Check /tmp/wzp-linux-build.log"' ERR
 if [ "$DO_PULL" = "1" ]; then
     echo ">>> Pulling latest..."
     cd "$BASE_DIR/data/source"
-    git checkout -- . 2>/dev/null || true
-    git pull origin feat/android-voip-client 2>&1 | tail -3
+    git reset --hard HEAD 2>/dev/null || true
+    git clean -fd 2>/dev/null || true
+    git gc --prune=now 2>/dev/null || true
+    git fetch origin feat/android-voip-client 2>&1 | tail -3
+    git reset --hard origin/feat/android-voip-client 2>/dev/null || true
 fi
 
 if [ "$DO_CLEAN" = "1" ]; then
@@ -70,7 +74,8 @@ find "$BASE_DIR/data/source" "$BASE_DIR/data/cache-linux" \
     ! -user 1000 -o ! -group 1000 2>/dev/null | \
     xargs -r chown 1000:1000 2>/dev/null || true
 
-notify "WZP Linux x86_64 build started..."
+GIT_HASH=$(cd "$BASE_DIR/data/source" && git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+notify "WZP Linux x86_64 build started [$GIT_HASH]..."
 
 echo ">>> Building in Docker..."
 docker run --rm --user 1000:1000 \
@@ -114,7 +119,7 @@ docker run --rm \
 URL=$(curl -s -F "file=@/tmp/wzp-linux-x86_64.tar.gz" -H "Authorization: $rusty_auth_token" "$rusty_address")
 if [ -n "$URL" ]; then
     echo "UPLOAD_URL=$URL"
-    notify "WZP Linux x86_64 binaries ready! $URL"
+    notify "WZP Linux x86_64 [$GIT_HASH] ready! $URL"
     echo ">>> Done! Binaries at: $URL"
 else
     notify "WZP Linux build FAILED - upload error"

scripts/build-tauri-android.sh

@@ -0,0 +1,253 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# =============================================================================
+# WZ Phone — Tauri 2.x Mobile Android APK build
+#
+# Builds the desktop/ Tauri app as an Android APK via cargo-tauri inside the
+# wzp-android-builder Docker image on SepehrHomeserverdk. Uploads the APK to
+# rustypaste, fires ntfy.sh/wzp notifications at start + finish, and SCPs the
+# APK back locally.
+#
+# Same pattern as build-and-notify.sh but for the Tauri mobile pipeline:
+#   - Source: desktop/src-tauri/  (not android/)
+#   - Build:  cargo tauri android build  (not gradlew assembleDebug)
+#   - Output: desktop/src-tauri/gen/android/.../*.apk
+#
+# Usage:
+#   ./scripts/build-tauri-android.sh                  # full pipeline (debug)
+#   ./scripts/build-tauri-android.sh --release        # release APK
+#   ./scripts/build-tauri-android.sh --no-pull        # skip git fetch
+#   ./scripts/build-tauri-android.sh --rust           # force-clean rust target
+#   ./scripts/build-tauri-android.sh --init           # also run `cargo tauri android init`
+#
+# Environment:
+#   WZP_BRANCH   Branch to build (default: feat/desktop-audio-rewrite)
+# =============================================================================
+
+REMOTE_HOST="SepehrHomeserverdk"
+BASE_DIR="/mnt/storage/manBuilder"
+NTFY_TOPIC="https://ntfy.sh/wzp"
+LOCAL_OUTPUT="target/tauri-android-apk"
+BRANCH="${WZP_BRANCH:-feat/desktop-audio-rewrite}"
+SSH_OPTS="-o ConnectTimeout=15 -o ServerAliveInterval=15 -o ServerAliveCountMax=4 -o LogLevel=ERROR"
+
+REBUILD_RUST=0
+DO_PULL=1
+DO_INIT=0
+BUILD_RELEASE=0
+for arg in "$@"; do
+    case "$arg" in
+        --rust)     REBUILD_RUST=1 ;;
+        --pull)     DO_PULL=1 ;;
+        --no-pull)  DO_PULL=0 ;;
+        --init)     DO_INIT=1 ;;
+        --release)  BUILD_RELEASE=1 ;;
+        -h|--help)
+            sed -n '3,30p' "$0"
+            exit 0
+            ;;
+    esac
+done
+
+log() { echo -e "\033[1;36m>>> $*\033[0m"; }
+ssh_cmd() { ssh -A $SSH_OPTS "$REMOTE_HOST" "$@"; }
+
+notify_local() { curl -s -d "$1" "$NTFY_TOPIC" > /dev/null 2>&1 || true; }
+
+mkdir -p "$LOCAL_OUTPUT"
+
+log "Uploading remote build script..."
+ssh_cmd "cat > /tmp/wzp-tauri-build.sh" <<'REMOTE_SCRIPT'
+#!/usr/bin/env bash
+set -euo pipefail
+
+BASE_DIR="/mnt/storage/manBuilder"
+NTFY_TOPIC="https://ntfy.sh/wzp"
+BRANCH="${1:-feat/desktop-audio-rewrite}"
+DO_PULL="${2:-1}"
+REBUILD_RUST="${3:-0}"
+DO_INIT="${4:-0}"
+BUILD_RELEASE="${5:-0}"
+
+LOG_FILE=/tmp/wzp-tauri-build.log
+GIT_HASH="unknown"  # populated after fetch
+ENV_FILE="$BASE_DIR/.env"
+
+notify() { curl -s -d "$1" "$NTFY_TOPIC" > /dev/null 2>&1 || true; }
+
+# Upload a file to rustypaste; print URL on stdout (or empty on failure).
+upload_to_rustypaste() {
+    local file="$1"
+    [ ! -f "$ENV_FILE" ] && { echo ""; return; }
+    # shellcheck disable=SC1090
+    source "$ENV_FILE"
+    if [ -n "${rusty_address:-}" ] && [ -n "${rusty_auth_token:-}" ]; then
+        curl -s -F "file=@$file" -H "Authorization: $rusty_auth_token" "$rusty_address" || echo ""
+    else
+        echo ""
+    fi
+}
+
+# On failure: upload the build log to rustypaste, then notify with hash + url.
+on_error() {
+    local line="$1"
+    local log_url
+    log_url=$(upload_to_rustypaste "$LOG_FILE" || echo "")
+    if [ -n "$log_url" ]; then
+        notify "WZP Tauri Android build FAILED [$GIT_HASH] (line $line)
+log: $log_url"
+    else
+        notify "WZP Tauri Android build FAILED [$GIT_HASH] (line $line) — log upload failed, see $LOG_FILE on remote"
+    fi
+}
+trap 'on_error $LINENO' ERR
+
+exec > >(tee "$LOG_FILE") 2>&1
+
+if [ "$DO_PULL" = "1" ]; then
+    echo ">>> git fetch + reset $BRANCH"
+    cd "$BASE_DIR/data/source"
+    git reset --hard HEAD 2>/dev/null || true
+    # NOTE: deliberately do NOT run `git clean -fd` here. It would wipe the
+    # tauri-generated `desktop/src-tauri/gen/android/` scaffold (gradlew,
+    # settings.gradle, etc.) which is expensive to recreate and breaks
+    # subsequent builds with "gradlew not found".
+    git gc --prune=now 2>/dev/null || true
+    git fetch origin "$BRANCH" 2>&1 | tail -3
+    git checkout "$BRANCH" 2>/dev/null || git checkout -b "$BRANCH" "origin/$BRANCH"
+    git reset --hard "origin/$BRANCH"
+    git submodule update --init || true
+fi
+
+GIT_HASH=$(cd "$BASE_DIR/data/source" && git rev-parse --short HEAD 2>/dev/null || echo unknown)
+GIT_MSG=$(cd "$BASE_DIR/data/source" && git log -1 --pretty=%s 2>/dev/null | head -c 60 || echo "?")
+notify "WZP Tauri Android build STARTED [$GIT_HASH] — $GIT_MSG"
+
+# Fix perms so uid 1000 can write
+find "$BASE_DIR/data/source" "$BASE_DIR/data/cache" \
+    ! -user 1000 -o ! -group 1000 2>/dev/null | \
+    xargs -r chown 1000:1000 2>/dev/null || true
+
+# Optionally clean rust target for android triples
+if [ "$REBUILD_RUST" = "1" ]; then
+    echo ">>> Cleaning Rust android target dirs..."
+    rm -rf "$BASE_DIR/data/cache/target/aarch64-linux-android" \
+           "$BASE_DIR/data/cache/target/armv7-linux-androideabi" \
+           "$BASE_DIR/data/cache/target/i686-linux-android" \
+           "$BASE_DIR/data/cache/target/x86_64-linux-android"
+fi
+
+# Profile flag
+PROFILE_FLAG="--debug"
+[ "$BUILD_RELEASE" = "1" ] && PROFILE_FLAG=""
+
+# Persist ~/.android (where the auto-generated debug.keystore lives) so every
+# build is signed with the SAME key. Without this, every fresh container gets
+# a new debug keystore and `adb install -r` fails with INSTALL_FAILED_UPDATE_
+# INCOMPATIBLE because the signature changed.
+mkdir -p "$BASE_DIR/data/cache/android-home"
+chown 1000:1000 "$BASE_DIR/data/cache/android-home" 2>/dev/null || true
+
+docker run --rm \
+    --user 1000:1000 \
+    -e DO_INIT="$DO_INIT" \
+    -e PROFILE_FLAG="$PROFILE_FLAG" \
+    -v "$BASE_DIR/data/source:/build/source" \
+    -v "$BASE_DIR/data/cache/cargo-registry:/home/builder/.cargo/registry" \
+    -v "$BASE_DIR/data/cache/cargo-git:/home/builder/.cargo/git" \
+    -v "$BASE_DIR/data/cache/target:/build/source/target" \
+    -v "$BASE_DIR/data/cache/gradle:/home/builder/.gradle" \
+    -v "$BASE_DIR/data/cache/android-home:/home/builder/.android" \
+    wzp-android-builder \
+    bash -c '
+set -euo pipefail
+cd /build/source/desktop
+
+echo ">>> npm install"
+npm install --silent 2>&1 | tail -5 || npm install 2>&1 | tail -20
+
+cd src-tauri
+
+# Run init if forced, OR if the gradle wrapper is missing. Just checking
+# for `gen/android` is not enough — Tauri creates a few subdirectories
+# during build (app/, buildSrc/, .gradle/) that survive a partial wipe and
+# would make a naive `[ ! -d gen/android ]` check return false even though
+# the build wrapper itself is gone.
+if [ "${DO_INIT}" = "1" ] || [ ! -x gen/android/gradlew ]; then
+    echo ">>> cargo tauri android init"
+    cargo tauri android init 2>&1 | tail -20
+fi
+
+# ─── wzp-native standalone cdylib (built with cargo-ndk, not cargo-tauri) ──
+# Produces libwzp_native.so which wzp-desktop dlopens at runtime via
+# libloading. Split exists because cargo-tauri`s linker wiring pulls
+# bionic private symbols into any cdylib with cc::Build C++, causing
+# __init_tcb+4 SIGSEGV. cargo-ndk uses the same linker path as the
+# legacy wzp-android crate which works.
+echo ">>> cargo ndk build -p wzp-native --release"
+JNI_ABI_DIR=gen/android/app/src/main/jniLibs/arm64-v8a
+mkdir -p "$JNI_ABI_DIR"
+(
+    cd /build/source
+    cargo ndk -t arm64-v8a -o desktop/src-tauri/gen/android/app/src/main/jniLibs \
+        build --release -p wzp-native 2>&1 | tail -10
+)
+if [ -f "$JNI_ABI_DIR/libwzp_native.so" ]; then
+    ls -lh "$JNI_ABI_DIR/libwzp_native.so"
+else
+    echo ">>> WARNING: libwzp_native.so not produced"
+fi
+
+echo ">>> cargo tauri android build ${PROFILE_FLAG} --target aarch64 --apk"
+cargo tauri android build ${PROFILE_FLAG} --target aarch64 --apk
+
+echo ""
+echo ">>> Build artifacts:"
+find gen/android -name "*.apk" -exec ls -lh {} \; 2>/dev/null
+'
+
+# Locate the produced APK
+APK=$(find "$BASE_DIR/data/source/desktop/src-tauri/gen/android" -name "*.apk" -type f 2>/dev/null | head -1)
+if [ -z "$APK" ] || [ ! -f "$APK" ]; then
+    LOG_URL=$(upload_to_rustypaste "$LOG_FILE" || echo "")
+    if [ -n "$LOG_URL" ]; then
+        notify "WZP Tauri Android build [$GIT_HASH]: no APK produced
+log: $LOG_URL"
+    else
+        notify "WZP Tauri Android build [$GIT_HASH]: no APK produced — log upload failed"
+    fi
+    exit 1
+fi
+APK_SIZE=$(du -h "$APK" | cut -f1)
+
+RUSTY_URL=$(upload_to_rustypaste "$APK" || echo "")
+if [ -n "$RUSTY_URL" ]; then
+    notify "WZP Tauri Android build OK [$GIT_HASH] ($APK_SIZE)
+$RUSTY_URL"
+else
+    notify "WZP Tauri Android build OK [$GIT_HASH] ($APK_SIZE) — rustypaste upload skipped"
+fi
+
+# Print path so the local script can grab it
+echo "APK_REMOTE_PATH=$APK"
+REMOTE_SCRIPT
+
+ssh_cmd "chmod +x /tmp/wzp-tauri-build.sh"
+
+notify_local "WZP Tauri Android build dispatched (branch=$BRANCH, release=$BUILD_RELEASE)"
+log "Triggering remote build (branch=$BRANCH)..."
+
+# Run; capture full output, last line is APK_REMOTE_PATH=...
+REMOTE_OUTPUT=$(ssh_cmd "/tmp/wzp-tauri-build.sh '$BRANCH' '$DO_PULL' '$REBUILD_RUST' '$DO_INIT' '$BUILD_RELEASE'" || true)
+echo "$REMOTE_OUTPUT" | tail -60
+
+APK_REMOTE=$(echo "$REMOTE_OUTPUT" | grep '^APK_REMOTE_PATH=' | tail -1 | cut -d= -f2-)
+if [ -n "$APK_REMOTE" ]; then
+    log "Downloading APK to $LOCAL_OUTPUT/wzp-tauri.apk..."
+    scp $SSH_OPTS "$REMOTE_HOST:$APK_REMOTE" "$LOCAL_OUTPUT/wzp-tauri.apk"
+    echo "  $LOCAL_OUTPUT/wzp-tauri.apk ($(du -h "$LOCAL_OUTPUT/wzp-tauri.apk" | cut -f1))"
+else
+    log "No APK produced — see ntfy / remote log /tmp/wzp-tauri-build.log"
+    exit 1
+fi

scripts/federation-test.sh

@@ -0,0 +1,280 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Federation Test Harness
+# Tests presence, audio delivery, and reconnection across 3 relays.
+#
+# Usage:
+#   ./scripts/federation-test.sh <relay1> <relay2> <relay3>
+#   ./scripts/federation-test.sh 172.16.81.175:4434 172.16.81.175:4435 172.16.81.175:4436
+#
+# Requires: wzp-client binary in PATH or target/release/
+
+RELAY1="${1:-127.0.0.1:4433}"
+RELAY2="${2:-127.0.0.1:4434}"
+RELAY3="${3:-127.0.0.1:4435}"
+ROOM="general"
+CLIENT="${WZP_CLIENT:-target/release/wzp-client}"
+AUDIO="/tmp/test-audio-60s.raw"
+RESULTS="/tmp/federation-test-results"
+DURATION=15  # seconds per test phase
+
+# Fixed seeds for reproducible identities
+SEED_A="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+SEED_B="bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+SEED_C="cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+SEED_D="dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
+
+log() { echo -e "\033[1;36m>>> $*\033[0m"; }
+err() { echo -e "\033[1;31mERROR: $*\033[0m" >&2; }
+pass() { echo -e "\033[1;32m  PASS: $*\033[0m"; }
+fail() { echo -e "\033[1;31m  FAIL: $*\033[0m"; }
+
+analyze() {
+    local path="$1" label="$2"
+    if [ ! -f "$path" ] || [ ! -s "$path" ]; then
+        fail "$label: NO FILE or empty"
+        return 1
+    fi
+    python3 -c "
+import struct, math
+with open('$path', 'rb') as f: data = f.read()
+if len(data) < 4:
+    print('  $label: EMPTY')
+    exit(1)
+samples = struct.unpack(f'<{len(data)//2}h', data)
+n = len(samples)
+rms = math.sqrt(sum(s*s for s in samples) / n) if n > 0 else 0
+dur = n / 48000
+nonzero = sum(1 for s in samples if s != 0)
+pct = 100 * nonzero / n if n > 0 else 0
+if rms > 50 and pct > 5:
+    print(f'  \033[32mPASS\033[0m: $label — {dur:.1f}s, RMS {rms:.0f}, {pct:.0f}% nonzero')
+else:
+    print(f'  \033[31mFAIL\033[0m: $label — {dur:.1f}s, RMS {rms:.0f}, {pct:.0f}% nonzero')
+    exit(1)
+" 2>/dev/null
+}
+
+cleanup() {
+    log "Cleaning up..."
+    kill ${PIDS[@]} 2>/dev/null || true
+    wait 2>/dev/null || true
+}
+trap cleanup EXIT
+
+mkdir -p "$RESULTS"
+PIDS=()
+
+# Generate test audio if missing
+if [ ! -f "$AUDIO" ]; then
+    log "Generating test audio..."
+    python3 -c "
+import struct, math, random
+RATE = 48000; samples = []
+t = 0
+while t < 60 * RATE:
+    burst = random.randint(int(RATE*0.2), int(RATE*0.8))
+    freq = random.choice([220,330,440,550,660,880])
+    amp = random.uniform(8000,16000)
+    for i in range(min(burst, 60*RATE-t)):
+        s = amp * math.sin(2*math.pi*freq*(t+i)/RATE)
+        samples.append(int(max(-32767,min(32767,s))))
+    t += burst
+    sil = random.randint(int(RATE*0.1), int(RATE*0.5))
+    samples.extend([0]*min(sil, 60*RATE-t)); t += sil
+with open('$AUDIO', 'wb') as f:
+    f.write(struct.pack(f'<{len(samples)}h', *samples))
+print(f'Generated {len(samples)/RATE:.1f}s')
+"
+fi
+
+echo ""
+echo "╔══════════════════════════════════════════════════════════╗"
+echo "║          WarzonePhone Federation Test Suite              ║"
+echo "╠══════════════════════════════════════════════════════════╣"
+echo "║  Relay 1: $RELAY1"
+echo "║  Relay 2: $RELAY2"
+echo "║  Relay 3: $RELAY3"
+echo "║  Room:    $ROOM"
+echo "║  Duration: ${DURATION}s per phase"
+echo "╚══════════════════════════════════════════════════════════╝"
+echo ""
+
+# ═══════════════════════════════════════════════════════════════
+# TEST 1: Basic 2-relay audio
+# ═══════════════════════════════════════════════════════════════
+log "TEST 1: Basic audio — A sends on Relay1, B records on Relay2"
+
+RUST_LOG=error $CLIENT --room $ROOM --seed $SEED_B --record "$RESULTS/t1_b.raw" "$RELAY2" &
+PIDS+=($!); sleep 2
+
+RUST_LOG=error $CLIENT --room $ROOM --seed $SEED_A --send-tone $DURATION "$RELAY1" &
+PIDS+=($!); sleep $((DURATION + 3))
+
+kill -INT ${PIDS[-2]} 2>/dev/null; sleep 3; kill -INT ${PIDS[-1]} 2>/dev/null; wait ${PIDS[-1]} ${PIDS[-2]} 2>/dev/null || true
+PIDS=("${PIDS[@]:0:${#PIDS[@]}-2}")
+
+analyze "$RESULTS/t1_b.raw" "Relay1→Relay2 audio"
+echo ""
+
+# ═══════════════════════════════════════════════════════════════
+# TEST 2: Reverse direction
+# ═══════════════════════════════════════════════════════════════
+log "TEST 2: Reverse — B sends on Relay2, A records on Relay1"
+
+RUST_LOG=error $CLIENT --room $ROOM --seed $SEED_A --record "$RESULTS/t2_a.raw" "$RELAY1" &
+PIDS+=($!); sleep 2
+
+RUST_LOG=error $CLIENT --room $ROOM --seed $SEED_B --send-tone $DURATION "$RELAY2" &
+PIDS+=($!); sleep $((DURATION + 3))
+
+kill -INT ${PIDS[-2]} 2>/dev/null; sleep 3; kill -INT ${PIDS[-1]} 2>/dev/null; wait ${PIDS[-1]} ${PIDS[-2]} 2>/dev/null || true
+PIDS=("${PIDS[@]:0:${#PIDS[@]}-2}")
+
+analyze "$RESULTS/t2_a.raw" "Relay2→Relay1 audio"
+echo ""
+
+# ═══════════════════════════════════════════════════════════════
+# TEST 3: 3-relay chain
+# ═══════════════════════════════════════════════════════════════
+log "TEST 3: 3-relay chain — A sends on Relay1, C records on Relay3"
+
+RUST_LOG=error $CLIENT --room $ROOM --seed $SEED_C --record "$RESULTS/t3_c.raw" "$RELAY3" &
+PIDS+=($!); sleep 2
+
+RUST_LOG=error $CLIENT --room $ROOM --seed $SEED_A --send-tone $DURATION "$RELAY1" &
+PIDS+=($!); sleep $((DURATION + 3))
+
+kill -INT ${PIDS[-2]} 2>/dev/null; sleep 3; kill -INT ${PIDS[-1]} 2>/dev/null; wait ${PIDS[-1]} ${PIDS[-2]} 2>/dev/null || true
+PIDS=("${PIDS[@]:0:${#PIDS[@]}-2}")
+
+analyze "$RESULTS/t3_c.raw" "Relay1→Relay3 (via Relay2) audio"
+echo ""
+
+# ═══════════════════════════════════════════════════════════════
+# TEST 4: File playback (simulated talk show)
+# ═══════════════════════════════════════════════════════════════
+log "TEST 4: File playback — A plays audio file on Relay1, B records on Relay2"
+
+RUST_LOG=error $CLIENT --room $ROOM --seed $SEED_B --record "$RESULTS/t4_b.raw" "$RELAY2" &
+PIDS+=($!); sleep 2
+
+RUST_LOG=error $CLIENT --room $ROOM --seed $SEED_A --send-file "$AUDIO" "$RELAY1" &
+PIDS+=($!); sleep 20  # file is 60s but we only wait 20
+
+kill -INT ${PIDS[-2]} 2>/dev/null; sleep 3; kill -INT ${PIDS[-1]} 2>/dev/null; wait ${PIDS[-1]} ${PIDS[-2]} 2>/dev/null || true
+PIDS=("${PIDS[@]:0:${#PIDS[@]}-2}")
+
+analyze "$RESULTS/t4_b.raw" "File playback Relay1→Relay2"
+echo ""
+
+# ═══════════════════════════════════════════════════════════════
+# TEST 5: Reconnection — B disconnects and rejoins
+# ═══════════════════════════════════════════════════════════════
+log "TEST 5: Reconnection — A sends, B joins/leaves/rejoins on Relay2"
+
+# A sends continuously
+RUST_LOG=error $CLIENT --room $ROOM --seed $SEED_A --send-tone 30 "$RELAY1" &
+A_PID=$!; PIDS+=($A_PID)
+sleep 2
+
+# B joins and records for 5s
+RUST_LOG=error $CLIENT --room $ROOM --seed $SEED_B --record "$RESULTS/t5_b_first.raw" "$RELAY2" &
+B_PID=$!; PIDS+=($B_PID)
+sleep 5
+kill -INT $B_PID 2>/dev/null; wait $B_PID 2>/dev/null || true
+
+log "  B disconnected, waiting 3s..."
+sleep 3
+
+# B rejoins and records for 5s
+RUST_LOG=error $CLIENT --room $ROOM --seed $SEED_B --record "$RESULTS/t5_b_rejoin.raw" "$RELAY2" &
+B_PID=$!; PIDS+=($B_PID)
+sleep 8
+kill -INT $B_PID 2>/dev/null; wait $B_PID 2>/dev/null || true
+kill -INT $A_PID 2>/dev/null; wait $A_PID 2>/dev/null || true
+
+analyze "$RESULTS/t5_b_first.raw" "B first join (before disconnect)"
+analyze "$RESULTS/t5_b_rejoin.raw" "B rejoin (after disconnect)"
+echo ""
+
+# ═══════════════════════════════════════════════════════════════
+# TEST 6: Multi-participant — 3 users on 3 relays
+# ═══════════════════════════════════════════════════════════════
+log "TEST 6: Multi-participant — A sends on R1, B records on R2, C records on R3"
+
+RUST_LOG=error $CLIENT --room $ROOM --seed $SEED_B --record "$RESULTS/t6_b.raw" "$RELAY2" &
+PIDS+=($!); sleep 1
+RUST_LOG=error $CLIENT --room $ROOM --seed $SEED_C --record "$RESULTS/t6_c.raw" "$RELAY3" &
+PIDS+=($!); sleep 1
+RUST_LOG=error $CLIENT --room $ROOM --seed $SEED_A --send-tone $DURATION "$RELAY1" &
+PIDS+=($!); sleep $((DURATION + 3))
+
+# Kill all 3
+for i in 1 2 3; do
+    kill -INT ${PIDS[-$i]} 2>/dev/null || true
+done
+wait 2>/dev/null || true
+PIDS=()
+
+analyze "$RESULTS/t6_b.raw" "B on Relay2 hears A on Relay1"
+analyze "$RESULTS/t6_c.raw" "C on Relay3 hears A on Relay1"
+echo ""
+
+# ═══════════════════════════════════════════════════════════════
+# TEST 7: Simultaneous senders
+# ═══════════════════════════════════════════════════════════════
+log "TEST 7: Simultaneous — A sends 440Hz on R1, B sends 880Hz on R2, C records on R3"
+
+RUST_LOG=error $CLIENT --room $ROOM --seed $SEED_C --record "$RESULTS/t7_c.raw" "$RELAY3" &
+PIDS+=($!); sleep 2
+RUST_LOG=error $CLIENT --room $ROOM --seed $SEED_A --send-tone $DURATION "$RELAY1" &
+PIDS+=($!);
+RUST_LOG=error $CLIENT --room $ROOM --seed $SEED_B --send-tone $DURATION "$RELAY2" &
+PIDS+=($!); sleep $((DURATION + 3))
+
+for i in 1 2 3; do kill ${PIDS[-$i]} 2>/dev/null || true; done
+wait 2>/dev/null || true
+PIDS=()
+
+analyze "$RESULTS/t7_c.raw" "C hears both A(R1) + B(R2)"
+echo ""
+
+# ═══════════════════════════════════════════════════════════════
+# SUMMARY
+# ═══════════════════════════════════════════════════════════════
+echo ""
+echo "╔══════════════════════════════════════════════════════════╗"
+echo "║                    TEST SUMMARY                          ║"
+echo "╠══════════════════════════════════════════════════════════╣"
+
+PASS=0; FAIL=0
+for f in "$RESULTS"/t*.raw; do
+    label=$(basename "$f" .raw)
+    if [ -s "$f" ]; then
+        rms=$(python3 -c "
+import struct, math
+with open('$f','rb') as f: d=f.read()
+s=struct.unpack(f'<{len(d)//2}h',d)
+print(f'{math.sqrt(sum(x*x for x in s)/len(s)):.0f}')
+" 2>/dev/null || echo "0")
+        if [ "$rms" -gt 50 ] 2>/dev/null; then
+            echo "║  ✓ $label (RMS: $rms)"
+            PASS=$((PASS + 1))
+        else
+            echo "║  ✗ $label (RMS: $rms)"
+            FAIL=$((FAIL + 1))
+        fi
+    else
+        echo "║  ✗ $label (NO FILE)"
+        FAIL=$((FAIL + 1))
+    fi
+done
+
+echo "╠══════════════════════════════════════════════════════════╣"
+echo "║  PASSED: $PASS  FAILED: $FAIL"
+echo "╚══════════════════════════════════════════════════════════╝"
+echo ""
+echo "Recordings saved to: $RESULTS/"
+echo "Play with: ffplay -f s16le -ar 48000 -ac 1 $RESULTS/<file>.raw"

scripts/mint-tmux.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# =============================================================================
+# mint-tmux.sh — run a command inside a persistent tmux session on the
+# Linux Mint build box so the user can attach and watch/interact at any time.
+#
+# Usage:
+#   mint-tmux.sh run   <window-name> <command...>   # start a new tmux window
+#   mint-tmux.sh send  <window-name> <text...>      # send keys to a window
+#   mint-tmux.sh kill  <window-name>                # close a window
+#   mint-tmux.sh list                               # list windows
+#   mint-tmux.sh tail  <window-name>                # dump last 200 lines
+#
+# Session name is always "wzp". Attach manually with:
+#   ssh -t root@172.16.81.192 tmux attach -t wzp
+#
+# If the wzp session doesn't exist yet, it's created automatically.
+# =============================================================================
+set -euo pipefail
+
+HOST="root@172.16.81.192"
+SESSION="wzp"
+SSH_OPTS="-o ConnectTimeout=10 -o LogLevel=ERROR"
+
+ensure_session() {
+    ssh $SSH_OPTS "$HOST" "
+        tmux has-session -t $SESSION 2>/dev/null || tmux new-session -d -s $SESSION -n home 'bash -l'
+    "
+}
+
+cmd="${1:-list}"
+shift || true
+
+case "$cmd" in
+    run)
+        WIN="${1:?window name required}"; shift
+        ensure_session
+        # Use a heredoc so multi-arg commands don't need escaping
+        CMD="$*"
+        ssh $SSH_OPTS "$HOST" bash -s <<REMOTE
+            if tmux list-windows -t $SESSION -F '#W' 2>/dev/null | grep -qx '$WIN'; then
+                tmux kill-window -t $SESSION:$WIN 2>/dev/null || true
+            fi
+            tmux new-window -t $SESSION -n '$WIN' "bash -l -c '$CMD; echo; echo --- window $WIN exited with code \\\$?; exec bash -l'"
+REMOTE
+        echo "Started '$WIN' in tmux session $SESSION on $HOST"
+        echo "Attach: ssh -t $HOST tmux attach -t $SESSION"
+        ;;
+    send)
+        WIN="${1:?window name required}"; shift
+        TEXT="$*"
+        ssh $SSH_OPTS "$HOST" "tmux send-keys -t $SESSION:$WIN '$TEXT' C-m"
+        ;;
+    kill)
+        WIN="${1:?window name required}"
+        ssh $SSH_OPTS "$HOST" "tmux kill-window -t $SESSION:$WIN 2>/dev/null || true"
+        ;;
+    list)
+        ensure_session
+        ssh $SSH_OPTS "$HOST" "tmux list-windows -t $SESSION"
+        ;;
+    tail)
+        WIN="${1:?window name required}"
+        ssh $SSH_OPTS "$HOST" "tmux capture-pane -p -t $SESSION:$WIN -S -200 || echo 'no such window'"
+        ;;
+    attach)
+        exec ssh -t $SSH_OPTS "$HOST" tmux attach -t $SESSION
+        ;;
+    *)
+        sed -n '3,20p' "$0"
+        exit 1
+        ;;
+esac

scripts/prep-linux-mint.sh

@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+# =============================================================================
+# Prepare a Linux Mint / Debian / Ubuntu x86_64 host as a full WarzonePhone
+# Android build environment. Installs everything the docker wzp-android-builder
+# image has, but directly on the host — so we can iterate locally without
+# docker layer caching, see real linker output, run gdbserver, etc.
+#
+# Target host: root@172.16.81.192 (Linux Mint on the LAN)
+#
+# Usage (from the macOS workstation):
+#   scp scripts/prep-linux-mint.sh root@172.16.81.192:/tmp/
+#   ssh root@172.16.81.192 'nohup bash /tmp/prep-linux-mint.sh > /var/log/wzp-prep.log 2>&1 &'
+#
+# The script is idempotent: safe to re-run if a step fails. Each stage tests
+# for its target before doing work. Progress + completion is pinged to
+# ntfy.sh/wzp so we can track it from the phone.
+#
+# On success the host has:
+#   - JDK 17
+#   - Android SDK (cmdline-tools + platforms 34/36, build-tools 34/35, NDK 26.1)
+#   - Node.js 20 LTS + npm
+#   - Rust stable + aarch64/armv7/i686/x86_64 android targets
+#   - cargo-ndk + cargo tauri-cli 2.x
+#   - /opt/wzp/warzonePhone  (cloned workspace checkout on feat/desktop-audio-rewrite)
+#
+# Everything lives under /opt/android-sdk and /opt/wzp so nothing leaks into $HOME.
+# =============================================================================
+set -euo pipefail
+
+NTFY_TOPIC="https://ntfy.sh/wzp"
+NDK_VERSION="26.1.10909125"
+ANDROID_API=34
+ANDROID_API_TAURI=36
+BUILD_TOOLS_TAURI="35.0.0"
+ANDROID_HOME=/opt/android-sdk
+WZP_DIR=/opt/wzp
+GIT_REPO="ssh://git@git.manko.yoga:222/manawenuz/wz-phone.git"
+GIT_BRANCH="feat/desktop-audio-rewrite"
+
+export DEBIAN_FRONTEND=noninteractive
+export ANDROID_HOME ANDROID_NDK_HOME="$ANDROID_HOME/ndk/$NDK_VERSION"
+export NDK_HOME="$ANDROID_NDK_HOME"
+export PATH="$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:/root/.cargo/bin:$PATH"
+
+notify() { curl -s -d "$1" "$NTFY_TOPIC" > /dev/null 2>&1 || true; }
+log()    { echo -e "\n\033[1;36m[prep-linux-mint]\033[0m $*"; }
+die()    { notify "wzp prep-linux-mint FAILED: $1"; echo "FATAL: $1" >&2; exit 1; }
+
+trap 'die "line $LINENO"' ERR
+
+notify "wzp prep-linux-mint STARTED on $(hostname) ($(whoami))"
+
+# ─── 1. Base packages ────────────────────────────────────────────────────────
+log "Installing base packages..."
+apt-get update -qq
+apt-get install -y --no-install-recommends \
+    build-essential \
+    ca-certificates \
+    cmake \
+    curl \
+    file \
+    git \
+    libasound2-dev \
+    libc6-dev \
+    libssl-dev \
+    openjdk-17-jdk-headless \
+    pkg-config \
+    unzip \
+    wget \
+    xz-utils \
+    zip
+
+# ─── 2. Android SDK + NDK ────────────────────────────────────────────────────
+if [ ! -x "$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" ]; then
+    log "Installing Android cmdline-tools..."
+    mkdir -p "$ANDROID_HOME/cmdline-tools"
+    cd /tmp
+    wget -q https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip -O cmdtools.zip
+    unzip -qo cmdtools.zip -d "$ANDROID_HOME/cmdline-tools"
+    mv "$ANDROID_HOME/cmdline-tools/cmdline-tools" "$ANDROID_HOME/cmdline-tools/latest"
+    rm cmdtools.zip
+else
+    log "cmdline-tools already installed"
+fi
+
+if [ ! -d "$ANDROID_HOME/ndk/$NDK_VERSION" ] || \
+   [ ! -d "$ANDROID_HOME/platforms/android-$ANDROID_API" ] || \
+   [ ! -d "$ANDROID_HOME/platforms/android-$ANDROID_API_TAURI" ]; then
+    log "Installing Android platforms + NDK $NDK_VERSION..."
+    yes | "$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" --licenses > /dev/null 2>&1 || true
+    "$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" --install \
+        "platforms;android-$ANDROID_API" \
+        "build-tools;$ANDROID_API.0.0" \
+        "platforms;android-$ANDROID_API_TAURI" \
+        "build-tools;$BUILD_TOOLS_TAURI" \
+        "ndk;$NDK_VERSION" \
+        "platform-tools" 2>&1 | grep -v '^\[' || true
+else
+    log "Android SDK components already installed"
+fi
+
+# ─── 3. Node.js 20 LTS ───────────────────────────────────────────────────────
+if ! command -v node >/dev/null 2>&1 || ! node --version | grep -q "^v20"; then
+    log "Installing Node.js 20 LTS..."
+    curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
+    apt-get install -y --no-install-recommends nodejs
+else
+    log "Node.js already at $(node --version)"
+fi
+
+# ─── 4. Rust + Android targets ───────────────────────────────────────────────
+if ! command -v rustup >/dev/null 2>&1; then
+    log "Installing rustup..."
+    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable
+fi
+. /root/.cargo/env
+
+log "Ensuring Rust android targets + cargo-ndk + cargo-tauri..."
+rustup target add \
+    aarch64-linux-android \
+    armv7-linux-androideabi \
+    i686-linux-android \
+    x86_64-linux-android
+command -v cargo-ndk  >/dev/null 2>&1 || cargo install cargo-ndk
+command -v cargo-tauri >/dev/null 2>&1 || cargo install tauri-cli --version "^2.0" --locked
+
+# ─── 5. Clone the workspace ──────────────────────────────────────────────────
+mkdir -p "$WZP_DIR"
+cd "$WZP_DIR"
+if [ -d warzonePhone/.git ]; then
+    log "Pulling latest on $GIT_BRANCH..."
+    cd warzonePhone
+    git fetch origin || true
+    git checkout "$GIT_BRANCH" 2>/dev/null || git checkout -b "$GIT_BRANCH" "origin/$GIT_BRANCH"
+    git reset --hard "origin/$GIT_BRANCH" || true
+else
+    log "Cloning warzonePhone from $GIT_REPO..."
+    # The public repo URL needs ssh keys; if unavailable, skip and let the user sort it later
+    if git clone --branch "$GIT_BRANCH" "$GIT_REPO" warzonePhone 2>/dev/null; then
+        log "  cloned ok"
+    else
+        log "  clone failed (no SSH keys for $GIT_REPO — skipping, user will rsync)"
+    fi
+fi
+
+# ─── 6. Persistent env for the user ──────────────────────────────────────────
+cat > /etc/profile.d/wzp-android.sh <<ENVEOF
+export ANDROID_HOME=$ANDROID_HOME
+export ANDROID_NDK_HOME=$ANDROID_HOME/ndk/$NDK_VERSION
+export NDK_HOME=\$ANDROID_NDK_HOME
+export PATH=\$ANDROID_HOME/cmdline-tools/latest/bin:\$ANDROID_HOME/platform-tools:/root/.cargo/bin:\$PATH
+ENVEOF
+chmod 644 /etc/profile.d/wzp-android.sh
+
+# ─── 7. Sanity summary ───────────────────────────────────────────────────────
+log "Sanity checks:"
+echo "  java:       $(java -version 2>&1 | head -1)"
+echo "  node:       $(node --version)"
+echo "  npm:        $(npm --version)"
+echo "  rustc:      $(rustc --version)"
+echo "  cargo-ndk:  $(cargo ndk --version 2>&1 | head -1)"
+echo "  cargo-tauri:$(cargo tauri --version 2>&1 | head -1)"
+echo "  NDK dir:    $ANDROID_NDK_HOME"
+echo "  WZP dir:    $WZP_DIR/warzonePhone"
+
+notify "wzp prep-linux-mint DONE on $(hostname) — ready at /opt/wzp/warzonePhone"
+log "All done."