feat: add Rust client library and mux daemon

Add donglora-client (clients/rust/) and donglora-mux (mux/rust/) as
Rust implementations of the existing Python client library and mux
daemon. Both are standalone Cargo projects with no-panic guarantees
enforced by clippy deny lints.

donglora-client provides protocol types, COBS framing, USB device
discovery, serial/mux transports, and a high-level Client<T> with
send/recv. donglora-mux is a fully async (tokio) multiplexer daemon
with dongle hot-plug reconnect, per-client bounded send queues,
SetConfig locking, and StartRx/StopRx reference counting.

52 unit tests across both crates. Updates README roadmap checkboxes
and CONTRIBUTING docs to reflect the new implementations.

src/daemon.rs

@@ -0,0 +1,628 @@
+//! Core mux daemon: dongle I/O, client management, reconnect loop.
+//!
+//! The daemon owns the USB serial connection and exposes Unix domain socket
+//! and optional TCP listeners. It routes commands from clients to the dongle
+//! and broadcasts/routes responses back.
+
+use std::collections::HashMap;
+use std::path::Path;
+use std::sync::Arc;
+use std::time::Duration;
+
+use donglora_client::{
+    encode_frame, FrameReader, CMD_TAG_SET_CONFIG, CMD_TAG_START_RX, CMD_TAG_STOP_RX,
+    RADIO_CONFIG_SIZE, RESP_TAG_OK, RESP_TAG_RX_PACKET,
+};
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::{TcpListener, UnixListener};
+use tokio::sync::{mpsc, oneshot, Mutex};
+
+/// A queued command: (client_id, raw_cmd_bytes).
+type QueuedCmd = (u64, Vec<u8>);
+
+/// Shared command receiver, wrapped for use across reconnect cycles.
+type SharedCmdRx = Arc<Mutex<mpsc::Receiver<QueuedCmd>>>;
+use tokio_util::sync::CancellationToken;
+use tracing::{debug, error, info, warn};
+
+use crate::intercept::{self, MuxState};
+use crate::session::ClientSession;
+
+/// Command timeout waiting for dongle response.
+const COMMAND_TIMEOUT: Duration = Duration::from_secs(10);
+
+/// Delay between dongle reconnect attempts.
+const RECONNECT_DELAY: Duration = Duration::from_secs(2);
+
+/// Max consecutive dongle read errors before declaring disconnect.
+const MAX_CONSECUTIVE_ERRORS: u32 = 3;
+
+/// Sentinel client ID for synthetic commands (e.g. auto StopRx).
+const SYNTHETIC_CLIENT_ID: u64 = u64::MAX;
+
+/// Shared mux state, protected by async mutex.
+type SharedState = Arc<Mutex<MuxInner>>;
+
+struct MuxInner {
+    sessions: HashMap<u64, ClientSession>,
+    mux_state: MuxState,
+}
+
+/// The multiplexer daemon.
+pub struct MuxDaemon {
+    serial_port: String,
+    socket_path: String,
+    tcp_addr: Option<(String, u16)>,
+    shutdown: CancellationToken,
+}
+
+impl MuxDaemon {
+    pub fn new(
+        serial_port: String,
+        socket_path: String,
+        tcp_addr: Option<(String, u16)>,
+        shutdown: CancellationToken,
+    ) -> Self {
+        Self {
+            serial_port,
+            socket_path,
+            tcp_addr,
+            shutdown,
+        }
+    }
+
+    /// Run the mux daemon. Returns when shutdown is signalled.
+    pub async fn run(&self) -> anyhow::Result<()> {
+        let state: SharedState = Arc::new(Mutex::new(MuxInner {
+            sessions: HashMap::new(),
+            mux_state: MuxState::new(),
+        }));
+
+        // Command channel: client handlers → dongle writer
+        let (cmd_tx, cmd_rx) = mpsc::channel::<(u64, Vec<u8>)>(64);
+        let cmd_rx = Arc::new(Mutex::new(cmd_rx));
+
+        // Pending response slot: dongle writer installs, dongle reader resolves
+        let pending_response: Arc<Mutex<Option<oneshot::Sender<Vec<u8>>>>> =
+            Arc::new(Mutex::new(None));
+
+        // Prepare socket directory
+        let sock_path = Path::new(&self.socket_path);
+        if let Some(parent) = sock_path.parent() {
+            tokio::fs::create_dir_all(parent).await.ok();
+        }
+        if sock_path.exists() {
+            tokio::fs::remove_file(sock_path).await.ok();
+        }
+
+        // Start Unix socket server
+        let unix_listener = UnixListener::bind(&self.socket_path)
+            .map_err(|e| anyhow::anyhow!("failed to bind Unix socket {}: {e}", self.socket_path))?;
+        info!("Unix socket listening on {}", self.socket_path);
+
+        // Start TCP server (optional)
+        let tcp_listener = if let Some((ref host, port)) = self.tcp_addr {
+            let addr = format!("{host}:{port}");
+            let listener = TcpListener::bind(&addr)
+                .await
+                .map_err(|e| anyhow::anyhow!("failed to bind TCP {addr}: {e}"))?;
+            info!("TCP listening on {addr}");
+            Some(listener)
+        } else {
+            None
+        };
+
+        // Spawn client accept tasks
+        tokio::spawn(accept_unix_clients(
+            unix_listener,
+            state.clone(),
+            cmd_tx.clone(),
+            self.shutdown.clone(),
+        ));
+        if let Some(listener) = tcp_listener {
+            tokio::spawn(accept_tcp_clients(
+                listener,
+                state.clone(),
+                cmd_tx.clone(),
+                self.shutdown.clone(),
+            ));
+        }
+
+        // Connect/reconnect loop
+        self.reconnect_loop(state, cmd_tx, cmd_rx, pending_response)
+            .await;
+
+        // Cleanup
+        info!("shutting down...");
+        if Path::new(&self.socket_path).exists() {
+            tokio::fs::remove_file(&self.socket_path).await.ok();
+        }
+        info!("stopped.");
+        Ok(())
+    }
+
+    async fn reconnect_loop(
+        &self,
+        state: SharedState,
+        _cmd_tx: mpsc::Sender<(u64, Vec<u8>)>, // kept alive to prevent channel close
+        cmd_rx: SharedCmdRx,
+        pending_response: Arc<Mutex<Option<oneshot::Sender<Vec<u8>>>>>,
+    ) {
+        loop {
+            if self.shutdown.is_cancelled() {
+                break;
+            }
+
+            info!("opening dongle on {}", self.serial_port);
+            let serial = loop {
+                if self.shutdown.is_cancelled() {
+                    return;
+                }
+                match open_and_ping(&self.serial_port).await {
+                    Ok(s) => break s,
+                    Err(e) => {
+                        debug!("could not open dongle: {e}");
+                        tokio::select! {
+                            () = self.shutdown.cancelled() => return,
+                            () = tokio::time::sleep(RECONNECT_DELAY) => continue,
+                        }
+                    }
+                }
+            };
+
+            info!("dongle connected");
+            let (serial_read, serial_write) = tokio::io::split(serial);
+
+            let dongle_lost = CancellationToken::new();
+
+            let reader_handle = tokio::spawn(dongle_reader(
+                serial_read,
+                state.clone(),
+                pending_response.clone(),
+                dongle_lost.clone(),
+                self.shutdown.clone(),
+            ));
+
+            let writer_handle = tokio::spawn(dongle_writer(
+                serial_write,
+                cmd_rx.clone(),
+                state.clone(),
+                pending_response.clone(),
+                dongle_lost.clone(),
+                self.shutdown.clone(),
+            ));
+
+            // Wait for dongle loss or shutdown
+            tokio::select! {
+                () = self.shutdown.cancelled() => {},
+                () = dongle_lost.cancelled() => {},
+            }
+
+            reader_handle.abort();
+            writer_handle.abort();
+            let _ = reader_handle.await;
+            let _ = writer_handle.await;
+
+            // Drain pending commands
+            {
+                let mut rx = cmd_rx.lock().await;
+                while rx.try_recv().is_ok() {}
+            }
+
+            if !self.shutdown.is_cancelled() {
+                info!("reconnecting in 2 seconds...");
+                tokio::select! {
+                    () = self.shutdown.cancelled() => return,
+                    () = tokio::time::sleep(RECONNECT_DELAY) => {},
+                }
+            }
+        }
+    }
+}
+
+// ── Dongle I/O ─────────────────────────────────────────────────────
+
+async fn open_and_ping(port: &str) -> anyhow::Result<tokio_serial::SerialStream> {
+    let builder = tokio_serial::new(port, 115_200).timeout(Duration::from_secs(2));
+    let mut serial = tokio_serial::SerialStream::open(&builder)
+        .map_err(|e| anyhow::anyhow!("failed to open {port}: {e}"))?;
+
+    let ping_frame = encode_frame(&[0]);
+    AsyncWriteExt::write_all(&mut serial, &ping_frame)
+        .await
+        .map_err(|e| anyhow::anyhow!("failed to write ping: {e}"))?;
+
+    let mut reader = FrameReader::new();
+    let mut buf = [0u8; 64];
+    let deadline = tokio::time::Instant::now() + Duration::from_secs(2);
+
+    loop {
+        let remaining = deadline.saturating_duration_since(tokio::time::Instant::now());
+        if remaining.is_zero() {
+            anyhow::bail!("ping timeout");
+        }
+
+        let n = tokio::select! {
+            result = serial.read(&mut buf) => {
+                result.map_err(|e| anyhow::anyhow!("serial read error: {e}"))?
+            }
+            () = tokio::time::sleep(remaining) => {
+                anyhow::bail!("ping timeout");
+            }
+        };
+
+        if n == 0 {
+            anyhow::bail!("serial port closed during ping");
+        }
+
+        for frame in reader.feed(&buf[..n]) {
+            if frame.first() == Some(&0) {
+                info!("dongle responded to Ping");
+                return Ok(serial);
+            }
+        }
+    }
+}
+
+async fn dongle_reader(
+    mut serial: tokio::io::ReadHalf<tokio_serial::SerialStream>,
+    state: SharedState,
+    pending_response: Arc<Mutex<Option<oneshot::Sender<Vec<u8>>>>>,
+    dongle_lost: CancellationToken,
+    shutdown: CancellationToken,
+) {
+    let mut reader = FrameReader::new();
+    let mut buf = [0u8; 512];
+    let mut consecutive_errors: u32 = 0;
+
+    loop {
+        if shutdown.is_cancelled() || dongle_lost.is_cancelled() {
+            return;
+        }
+
+        let read_result = tokio::select! {
+            result = serial.read(&mut buf) => result,
+            () = shutdown.cancelled() => return,
+            () = dongle_lost.cancelled() => return,
+        };
+
+        match read_result {
+            Ok(0) => {
+                error!("serial port closed");
+                resolve_pending_with_error(&pending_response).await;
+                dongle_lost.cancel();
+                return;
+            }
+            Ok(n) => {
+                consecutive_errors = 0;
+                for frame in reader.feed(&buf[..n]) {
+                    dispatch_frame(&frame, &state, &pending_response).await;
+                }
+            }
+            Err(e) => {
+                consecutive_errors += 1;
+                if consecutive_errors >= MAX_CONSECUTIVE_ERRORS {
+                    error!("dongle read error (giving up after {consecutive_errors}): {e}");
+                    resolve_pending_with_error(&pending_response).await;
+                    dongle_lost.cancel();
+                    return;
+                }
+                warn!("dongle read glitch ({consecutive_errors}/{MAX_CONSECUTIVE_ERRORS}): {e}");
+                tokio::time::sleep(Duration::from_millis(100)).await;
+            }
+        }
+    }
+}
+
+async fn dispatch_frame(
+    frame: &[u8],
+    state: &SharedState,
+    pending_response: &Arc<Mutex<Option<oneshot::Sender<Vec<u8>>>>>,
+) {
+    let Some(&tag) = frame.first() else {
+        return;
+    };
+
+    if tag == RESP_TAG_RX_PACKET {
+        let cobs_frame = encode_frame(frame);
+        let inner = state.lock().await;
+        for session in inner.sessions.values() {
+            session.enqueue(cobs_frame.clone());
+        }
+    } else {
+        let mut slot = pending_response.lock().await;
+        if let Some(sender) = slot.take() {
+            let _ = sender.send(frame.to_vec());
+        } else {
+            warn!("unsolicited non-RxPacket response (tag {tag}) — dropped");
+        }
+    }
+}
+
+async fn resolve_pending_with_error(
+    pending_response: &Arc<Mutex<Option<oneshot::Sender<Vec<u8>>>>>,
+) {
+    let mut slot = pending_response.lock().await;
+    if let Some(sender) = slot.take() {
+        let _ = sender.send(vec![5, 1]); // Error(RadioBusy)
+    }
+}
+
+async fn dongle_writer(
+    mut serial: tokio::io::WriteHalf<tokio_serial::SerialStream>,
+    cmd_rx: SharedCmdRx,
+    state: SharedState,
+    pending_response: Arc<Mutex<Option<oneshot::Sender<Vec<u8>>>>>,
+    dongle_lost: CancellationToken,
+    shutdown: CancellationToken,
+) {
+    loop {
+        // Pull next command from queue
+        let (client_id, raw_cmd) = {
+            let mut rx = cmd_rx.lock().await;
+            tokio::select! {
+                cmd = rx.recv() => {
+                    match cmd {
+                        Some(c) => c,
+                        None => return,
+                    }
+                }
+                () = shutdown.cancelled() => return,
+                () = dongle_lost.cancelled() => return,
+            }
+        };
+
+        // Check for interception
+        let intercepted = {
+            let mut inner = state.lock().await;
+            let locked = inner.mux_state.locked_config;
+            intercept::maybe_intercept(
+                &raw_cmd,
+                client_id,
+                &mut inner.sessions,
+                &locked,
+            )
+        };
+        if let Some(synthetic) = intercepted {
+            let inner = state.lock().await;
+            if let Some(session) = inner.sessions.get(&client_id) {
+                session.enqueue(encode_frame(&synthetic));
+            }
+            continue;
+        }
+
+        // Install oneshot for the response
+        let (resp_tx, resp_rx) = oneshot::channel();
+        {
+            let mut slot = pending_response.lock().await;
+            *slot = Some(resp_tx);
+        }
+
+        // Send command to dongle
+        let cobs_frame = encode_frame(&raw_cmd);
+        if let Err(e) = AsyncWriteExt::write_all(&mut serial, &cobs_frame).await {
+            error!("dongle write error: {e}");
+            resolve_pending_with_error(&pending_response).await;
+            dongle_lost.cancel();
+            return;
+        }
+
+        // Wait for response
+        let response = match tokio::time::timeout(COMMAND_TIMEOUT, resp_rx).await {
+            Ok(Ok(resp)) => resp,
+            Ok(Err(_)) => {
+                warn!("response channel dropped");
+                vec![5, 1]
+            }
+            Err(_) => {
+                error!("dongle response timeout");
+                let mut slot = pending_response.lock().await;
+                *slot = None;
+                vec![5, 1]
+            }
+        };
+
+        // Track state on successful forward
+        let cmd_tag = raw_cmd.first().copied().unwrap_or(0xFF);
+        let resp_tag = response.first().copied().unwrap_or(0xFF);
+        {
+            let mut inner = state.lock().await;
+            if cmd_tag == CMD_TAG_SET_CONFIG && resp_tag == RESP_TAG_OK {
+                if let Some(config_bytes) = raw_cmd.get(1..1 + RADIO_CONFIG_SIZE) {
+                    let mut locked = [0u8; RADIO_CONFIG_SIZE];
+                    locked.copy_from_slice(config_bytes);
+                    inner.mux_state.locked_config = Some(locked);
+                    info!("radio config locked");
+                }
+            } else if cmd_tag == CMD_TAG_START_RX && resp_tag == RESP_TAG_OK {
+                if let Some(session) = inner.sessions.get_mut(&client_id) {
+                    session.rx_interested = true;
+                }
+            } else if cmd_tag == CMD_TAG_STOP_RX
+                && resp_tag == RESP_TAG_OK
+                && let Some(session) = inner.sessions.get_mut(&client_id)
+            {
+                session.rx_interested = false;
+            }
+        }
+
+        // Route response to commanding client
+        if client_id != SYNTHETIC_CLIENT_ID {
+            let inner = state.lock().await;
+            if let Some(session) = inner.sessions.get(&client_id) {
+                session.enqueue(encode_frame(&response));
+            }
+        }
+    }
+}
+
+// ── Client management ──────────────────────────────────────────────
+
+async fn accept_unix_clients(
+    listener: UnixListener,
+    state: SharedState,
+    cmd_tx: mpsc::Sender<(u64, Vec<u8>)>,
+    shutdown: CancellationToken,
+) {
+    loop {
+        let accept_result = tokio::select! {
+            result = listener.accept() => result,
+            () = shutdown.cancelled() => return,
+        };
+
+        match accept_result {
+            Ok((stream, _addr)) => {
+                let (read_half, write_half) = stream.into_split();
+                spawn_client(read_half, write_half, state.clone(), cmd_tx.clone(), shutdown.clone());
+            }
+            Err(e) => warn!("Unix accept error: {e}"),
+        }
+    }
+}
+
+async fn accept_tcp_clients(
+    listener: TcpListener,
+    state: SharedState,
+    cmd_tx: mpsc::Sender<(u64, Vec<u8>)>,
+    shutdown: CancellationToken,
+) {
+    loop {
+        let accept_result = tokio::select! {
+            result = listener.accept() => result,
+            () = shutdown.cancelled() => return,
+        };
+
+        match accept_result {
+            Ok((stream, addr)) => {
+                debug!("TCP connection from {addr}");
+                let (read_half, write_half) = stream.into_split();
+                spawn_client(read_half, write_half, state.clone(), cmd_tx.clone(), shutdown.clone());
+            }
+            Err(e) => warn!("TCP accept error: {e}"),
+        }
+    }
+}
+
+fn spawn_client<R, W>(
+    read_half: R,
+    write_half: W,
+    state: SharedState,
+    cmd_tx: mpsc::Sender<(u64, Vec<u8>)>,
+    shutdown: CancellationToken,
+) where
+    R: AsyncReadExt + Unpin + Send + 'static,
+    W: AsyncWriteExt + Unpin + Send + 'static,
+{
+    let (session, send_rx) = ClientSession::new();
+    let client_id = session.id;
+    let label = session.label();
+
+    let state_clone = state.clone();
+    let cmd_tx_clone = cmd_tx.clone();
+
+    tokio::spawn(async move {
+        {
+            let mut inner = state_clone.lock().await;
+            inner.sessions.insert(client_id, session);
+            info!("{label} connected ({} total)", inner.sessions.len());
+        }
+
+        let writer_shutdown = shutdown.clone();
+        let writer_handle = tokio::spawn(client_writer(write_half, send_rx, writer_shutdown));
+
+        client_reader(read_half, client_id, cmd_tx_clone.clone(), shutdown).await;
+
+        writer_handle.abort();
+        let _ = writer_handle.await;
+
+        remove_client(client_id, &state_clone, &label, &cmd_tx_clone).await;
+    });
+}
+
+async fn client_reader<R: AsyncReadExt + Unpin>(
+    mut read_half: R,
+    client_id: u64,
+    cmd_tx: mpsc::Sender<(u64, Vec<u8>)>,
+    shutdown: CancellationToken,
+) {
+    let mut reader = FrameReader::new();
+    let mut buf = [0u8; 4096];
+
+    loop {
+        let read_result = tokio::select! {
+            result = read_half.read(&mut buf) => result,
+            () = shutdown.cancelled() => return,
+        };
+
+        match read_result {
+            Ok(0) => return,
+            Ok(n) => {
+                for frame in reader.feed(&buf[..n]) {
+                    if cmd_tx.send((client_id, frame)).await.is_err() {
+                        return;
+                    }
+                }
+            }
+            Err(_) => return,
+        }
+    }
+}
+
+async fn client_writer<W: AsyncWriteExt + Unpin>(
+    mut write_half: W,
+    mut send_rx: mpsc::Receiver<Vec<u8>>,
+    shutdown: CancellationToken,
+) {
+    loop {
+        let frame = tokio::select! {
+            f = send_rx.recv() => {
+                match f {
+                    Some(f) => f,
+                    None => return,
+                }
+            }
+            () = shutdown.cancelled() => return,
+        };
+
+        if AsyncWriteExt::write_all(&mut write_half, &frame)
+            .await
+            .is_err()
+        {
+            return;
+        }
+    }
+}
+
+async fn remove_client(
+    client_id: u64,
+    state: &SharedState,
+    label: &str,
+    cmd_tx: &mpsc::Sender<(u64, Vec<u8>)>,
+) {
+    let mut inner = state.lock().await;
+
+    let was_interested = inner
+        .sessions
+        .get(&client_id)
+        .is_some_and(|s| s.rx_interested);
+
+    inner.sessions.remove(&client_id);
+    info!("{label} disconnected ({} remain)", inner.sessions.len());
+
+    // If last RX-interested client gone, send synthetic StopRx
+    if was_interested && intercept::rx_interest_count(&inner.sessions) == 0 {
+        info!("last RX-interested client gone — sending StopRx");
+        // Drop the lock before sending to avoid deadlock
+        drop(inner);
+        let _ = cmd_tx
+            .send((SYNTHETIC_CLIENT_ID, vec![CMD_TAG_STOP_RX]))
+            .await;
+        return;
+    }
+
+    // Reset locked config when all clients are gone
+    if inner.sessions.is_empty() && inner.mux_state.locked_config.is_some() {
+        info!("all clients gone — config lock released");
+        inner.mux_state.locked_config = None;
+    }
+}

src/intercept.rs

@@ -0,0 +1,291 @@
+//! Smart multiplexing: SetConfig locking, StartRx/StopRx reference counting.
+//!
+//! The mux intercepts certain commands to avoid redundant dongle operations
+//! when multiple clients are connected. Intercepted commands get synthetic
+//! responses without hitting the physical dongle.
+
+use std::collections::HashMap;
+
+use donglora_client::{
+    CMD_TAG_SET_CONFIG, CMD_TAG_START_RX, CMD_TAG_STOP_RX, ERROR_INVALID_CONFIG, RADIO_CONFIG_SIZE,
+    RESP_TAG_ERROR, RESP_TAG_OK,
+};
+use tracing::{debug, warn};
+
+use crate::session::ClientSession;
+
+/// Mux-level state for interception logic.
+pub struct MuxState {
+    /// Raw 13-byte RadioConfig, locked once set by any client with others connected.
+    pub locked_config: Option<[u8; RADIO_CONFIG_SIZE]>,
+}
+
+impl MuxState {
+    pub fn new() -> Self {
+        Self {
+            locked_config: None,
+        }
+    }
+}
+
+/// Check if a command should be intercepted (synthetic response) vs forwarded to the dongle.
+///
+/// Returns `Some(response_bytes)` if intercepted, `None` to forward normally.
+pub fn maybe_intercept(
+    raw_cmd: &[u8],
+    client_id: u64,
+    sessions: &mut HashMap<u64, ClientSession>,
+    locked_config: &Option<[u8; RADIO_CONFIG_SIZE]>,
+) -> Option<Vec<u8>> {
+    let cmd_tag = *raw_cmd.first()?;
+
+    match cmd_tag {
+        CMD_TAG_SET_CONFIG => intercept_set_config(raw_cmd, client_id, sessions, locked_config),
+        CMD_TAG_START_RX => intercept_start_rx(client_id, sessions),
+        CMD_TAG_STOP_RX => intercept_stop_rx(client_id, sessions),
+        _ => None,
+    }
+}
+
+fn intercept_set_config(
+    raw_cmd: &[u8],
+    client_id: u64,
+    sessions: &HashMap<u64, ClientSession>,
+    locked_config: &Option<[u8; RADIO_CONFIG_SIZE]>,
+) -> Option<Vec<u8>> {
+    let config_bytes = raw_cmd.get(1..1 + RADIO_CONFIG_SIZE)?;
+
+    // Single client — allow free config changes (scanner mode)
+    if sessions.len() <= 1 {
+        return None;
+    }
+
+    // First SetConfig with multiple clients — forward and lock on success
+    let Some(locked) = locked_config else {
+        return None;
+    };
+
+    // Same config — reply Ok without hitting the dongle
+    if config_bytes == locked.as_slice() {
+        let label = sessions
+            .get(&client_id)
+            .map(ClientSession::label)
+            .unwrap_or_else(|| format!("id-{client_id}"));
+        debug!("{label}: SetConfig matches locked config — Ok");
+        return Some(vec![RESP_TAG_OK]);
+    }
+
+    // Different config — reject
+    let label = sessions
+        .get(&client_id)
+        .map(ClientSession::label)
+        .unwrap_or_else(|| format!("id-{client_id}"));
+    warn!("{label}: SetConfig rejected (conflicts with locked config)");
+    Some(vec![RESP_TAG_ERROR, ERROR_INVALID_CONFIG])
+}
+
+fn intercept_start_rx(
+    client_id: u64,
+    sessions: &mut HashMap<u64, ClientSession>,
+) -> Option<Vec<u8>> {
+    let client = sessions.get(&client_id)?;
+
+    // Already interested — no-op
+    if client.rx_interested {
+        return Some(vec![RESP_TAG_OK]);
+    }
+
+    // Others already receiving — just mark this client
+    if rx_interest_count(sessions) > 0 {
+        if let Some(c) = sessions.get_mut(&client_id) {
+            c.rx_interested = true;
+        }
+        return Some(vec![RESP_TAG_OK]);
+    }
+
+    // First interested client — forward to dongle
+    None
+}
+
+fn intercept_stop_rx(
+    client_id: u64,
+    sessions: &mut HashMap<u64, ClientSession>,
+) -> Option<Vec<u8>> {
+    let client = sessions.get(&client_id)?;
+
+    // Wasn't interested — no-op
+    if !client.rx_interested {
+        return Some(vec![RESP_TAG_OK]);
+    }
+
+    // Mark as not interested
+    if let Some(c) = sessions.get_mut(&client_id) {
+        c.rx_interested = false;
+    }
+
+    // Others still interested — don't stop the dongle
+    if rx_interest_count(sessions) > 0 {
+        return Some(vec![RESP_TAG_OK]);
+    }
+
+    // Last interested client — forward StopRx to dongle
+    None
+}
+
+/// Count how many sessions have rx_interested set.
+pub fn rx_interest_count(sessions: &HashMap<u64, ClientSession>) -> usize {
+    sessions.values().filter(|s| s.rx_interested).count()
+}
+
+// ── Tests ──────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn make_sessions(n: usize) -> HashMap<u64, ClientSession> {
+        let mut map = HashMap::new();
+        for _ in 0..n {
+            let (session, _rx) = ClientSession::new();
+            let id = session.id;
+            map.insert(id, session);
+        }
+        map
+    }
+
+    fn first_id(sessions: &HashMap<u64, ClientSession>) -> u64 {
+        *sessions.keys().min().unwrap()
+    }
+
+    fn second_id(sessions: &HashMap<u64, ClientSession>) -> u64 {
+        let mut ids: Vec<u64> = sessions.keys().copied().collect();
+        ids.sort();
+        ids[1]
+    }
+
+    // ── SetConfig ──────────────────────────────���───────────────────
+
+    #[test]
+    fn set_config_single_client_forwards() {
+        let mut sessions = make_sessions(1);
+        let locked = None;
+        let id = first_id(&sessions);
+        let cmd = [CMD_TAG_SET_CONFIG, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
+        assert!(maybe_intercept(&cmd, id, &mut sessions, &locked).is_none());
+    }
+
+    #[test]
+    fn set_config_first_with_multiple_forwards() {
+        let mut sessions = make_sessions(2);
+        let locked = None;
+        let id = first_id(&sessions);
+        let cmd = [CMD_TAG_SET_CONFIG, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13];
+        assert!(maybe_intercept(&cmd, id, &mut sessions, &locked).is_none());
+    }
+
+    #[test]
+    fn set_config_matching_returns_ok() {
+        let mut sessions = make_sessions(2);
+        let config = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13];
+        let locked = Some(config);
+        let id = first_id(&sessions);
+        let mut cmd = vec![CMD_TAG_SET_CONFIG];
+        cmd.extend_from_slice(&config);
+        assert_eq!(maybe_intercept(&cmd, id, &mut sessions, &locked), Some(vec![RESP_TAG_OK]));
+    }
+
+    #[test]
+    fn set_config_conflicting_returns_error() {
+        let mut sessions = make_sessions(2);
+        let locked = Some([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13]);
+        let id = first_id(&sessions);
+        let mut cmd = vec![CMD_TAG_SET_CONFIG];
+        cmd.extend_from_slice(&[99, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13]);
+        assert_eq!(
+            maybe_intercept(&cmd, id, &mut sessions, &locked),
+            Some(vec![RESP_TAG_ERROR, ERROR_INVALID_CONFIG])
+        );
+    }
+
+    // ── StartRx ────────────────────────────────────────────────────
+
+    #[test]
+    fn start_rx_first_client_forwards() {
+        let mut sessions = make_sessions(1);
+        let locked = None;
+        let id = first_id(&sessions);
+        assert!(maybe_intercept(&[CMD_TAG_START_RX], id, &mut sessions, &locked).is_none());
+    }
+
+    #[test]
+    fn start_rx_already_interested_returns_ok() {
+        let mut sessions = make_sessions(1);
+        let locked = None;
+        let id = first_id(&sessions);
+        sessions.get_mut(&id).unwrap().rx_interested = true;
+        assert_eq!(
+            maybe_intercept(&[CMD_TAG_START_RX], id, &mut sessions, &locked),
+            Some(vec![RESP_TAG_OK])
+        );
+    }
+
+    #[test]
+    fn start_rx_others_interested_marks_and_returns_ok() {
+        let mut sessions = make_sessions(2);
+        let locked = None;
+        let id1 = first_id(&sessions);
+        let id2 = second_id(&sessions);
+        sessions.get_mut(&id1).unwrap().rx_interested = true;
+        let result = maybe_intercept(&[CMD_TAG_START_RX], id2, &mut sessions, &locked);
+        assert_eq!(result, Some(vec![RESP_TAG_OK]));
+        assert!(sessions.get(&id2).unwrap().rx_interested);
+    }
+
+    // ── StopRx ─────────────────────────────────────────────────────
+
+    #[test]
+    fn stop_rx_not_interested_returns_ok() {
+        let mut sessions = make_sessions(1);
+        let locked = None;
+        let id = first_id(&sessions);
+        assert_eq!(
+            maybe_intercept(&[CMD_TAG_STOP_RX], id, &mut sessions, &locked),
+            Some(vec![RESP_TAG_OK])
+        );
+    }
+
+    #[test]
+    fn stop_rx_others_remain_returns_ok() {
+        let mut sessions = make_sessions(2);
+        let locked = None;
+        let id1 = first_id(&sessions);
+        let id2 = second_id(&sessions);
+        sessions.get_mut(&id1).unwrap().rx_interested = true;
+        sessions.get_mut(&id2).unwrap().rx_interested = true;
+        let result = maybe_intercept(&[CMD_TAG_STOP_RX], id1, &mut sessions, &locked);
+        assert_eq!(result, Some(vec![RESP_TAG_OK]));
+        assert!(!sessions.get(&id1).unwrap().rx_interested);
+    }
+
+    #[test]
+    fn stop_rx_last_interested_forwards() {
+        let mut sessions = make_sessions(1);
+        let locked = None;
+        let id = first_id(&sessions);
+        sessions.get_mut(&id).unwrap().rx_interested = true;
+        assert!(maybe_intercept(&[CMD_TAG_STOP_RX], id, &mut sessions, &locked).is_none());
+        assert!(!sessions.get(&id).unwrap().rx_interested);
+    }
+
+    // ── Other commands ─────────────────────────────────────────────
+
+    #[test]
+    fn other_commands_not_intercepted() {
+        let mut sessions = make_sessions(1);
+        let locked = None;
+        let id = first_id(&sessions);
+        for tag in [0u8, 1, 5, 6, 7, 8] {
+            assert!(maybe_intercept(&[tag], id, &mut sessions, &locked).is_none());
+        }
+    }
+}

src/main.rs

@@ -0,0 +1,119 @@
+//! DongLoRa USB Multiplexer — share one dongle with multiple applications.
+//!
+//! Owns the USB serial connection and exposes a Unix domain socket (and
+//! optional TCP) that speaks the same COBS-framed protocol. Clients connect
+//! and get solicited responses routed, RxPackets broadcast, and StartRx/StopRx
+//! reference-counted.
+
+mod daemon;
+mod intercept;
+mod session;
+
+use clap::Parser;
+use tokio_util::sync::CancellationToken;
+use tracing::info;
+
+#[derive(Parser)]
+#[command(name = "donglora-mux", about = "DongLoRa USB Multiplexer")]
+struct Args {
+    /// Serial port (auto-detect by USB VID:PID if omitted)
+    #[arg(short, long)]
+    port: Option<String>,
+
+    /// Unix socket path (default: XDG or /tmp/donglora-mux.sock)
+    #[arg(short, long)]
+    socket: Option<String>,
+
+    /// TCP listen address [HOST:]PORT (default: 0.0.0.0:5741, "none" to disable)
+    #[arg(short, long, default_value = "0.0.0.0:5741")]
+    tcp: String,
+
+    /// Enable debug logging
+    #[arg(short, long)]
+    verbose: bool,
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let args = Args::parse();
+
+    // Init tracing — daemon-style: wall-clock time, level, message
+    let filter = if args.verbose { "debug" } else { "info" };
+    tracing_subscriber::fmt()
+        .with_env_filter(
+            tracing_subscriber::EnvFilter::try_from_default_env()
+                .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new(filter)),
+        )
+        .with_target(false)
+        .init();
+
+    // Resolve serial port
+    let port = match args.port {
+        Some(p) => p,
+        None => {
+            tokio::task::spawn_blocking(|| {
+                donglora_client::find_port().unwrap_or_else(|| {
+                    info!("waiting for DongLoRa device...");
+                    donglora_client::wait_for_device()
+                })
+            })
+            .await
+            .map_err(|e| anyhow::anyhow!("device discovery task failed: {e}"))?
+        }
+    };
+
+    // Resolve socket path
+    let socket_path = args
+        .socket
+        .unwrap_or_else(donglora_client::default_socket_path);
+
+    // Parse TCP address
+    let tcp_addr = parse_tcp_addr(&args.tcp);
+
+    // Shutdown token
+    let shutdown = CancellationToken::new();
+
+    // Install signal handlers
+    let sig_shutdown = shutdown.clone();
+    tokio::spawn(async move {
+        if let Err(e) = signal_handler(sig_shutdown).await {
+            tracing::error!("signal handler error: {e}");
+        }
+    });
+
+    // Run the daemon
+    let daemon = daemon::MuxDaemon::new(port, socket_path, tcp_addr, shutdown);
+    daemon.run().await
+}
+
+fn parse_tcp_addr(tcp: &str) -> Option<(String, u16)> {
+    if tcp.eq_ignore_ascii_case("none") {
+        return None;
+    }
+    if let Some((host, port_str)) = tcp.rsplit_once(':')
+        && let Ok(port) = port_str.parse()
+    {
+        return Some((host.to_string(), port));
+    }
+    if let Ok(port) = tcp.parse() {
+        return Some(("0.0.0.0".to_string(), port));
+    }
+    None
+}
+
+async fn signal_handler(shutdown: CancellationToken) -> anyhow::Result<()> {
+    let mut sigint =
+        tokio::signal::unix::signal(tokio::signal::unix::SignalKind::interrupt())
+            .map_err(|e| anyhow::anyhow!("failed to register SIGINT handler: {e}"))?;
+    let mut sigterm =
+        tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())
+            .map_err(|e| anyhow::anyhow!("failed to register SIGTERM handler: {e}"))?;
+
+    tokio::select! {
+        _ = sigint.recv() => info!("received SIGINT"),
+        _ = sigterm.recv() => info!("received SIGTERM"),
+    }
+
+    shutdown.cancel();
+    Ok(())
+}

src/session.rs

@@ -0,0 +1,57 @@
+//! Per-client session state and bounded send queue.
+//!
+//! Each connected client gets a [`ClientSession`] that tracks its ID,
+//! RX interest flag, and a bounded channel for outgoing COBS frames.
+
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use tokio::sync::mpsc;
+use tracing::warn;
+
+/// Bounded send queue capacity per client.
+const SEND_QUEUE_CAP: usize = 256;
+
+/// Global client ID counter.
+static NEXT_CLIENT_ID: AtomicU64 = AtomicU64::new(0);
+
+/// Per-client state tracked by the mux daemon.
+pub struct ClientSession {
+    /// Unique client identifier.
+    pub id: u64,
+    /// Whether this client has called StartRx.
+    pub rx_interested: bool,
+    /// Sender half of the bounded channel to the client's writer task.
+    tx: mpsc::Sender<Vec<u8>>,
+}
+
+impl ClientSession {
+    /// Create a new session. Returns the session and the receiver half
+    /// for the client's writer task to drain.
+    pub fn new() -> (Self, mpsc::Receiver<Vec<u8>>) {
+        let id = NEXT_CLIENT_ID.fetch_add(1, Ordering::Relaxed);
+        let (tx, rx) = mpsc::channel(SEND_QUEUE_CAP);
+        let session = Self {
+            id,
+            rx_interested: false,
+            tx,
+        };
+        (session, rx)
+    }
+
+    /// Human-readable label for logging.
+    pub fn label(&self) -> String {
+        format!("client-{}", self.id)
+    }
+
+    /// Best-effort enqueue of a COBS frame for sending to this client.
+    ///
+    /// If the channel is full (slow client), the frame is dropped with a warning.
+    /// This prevents backpressure from one slow client blocking the entire mux.
+    pub fn enqueue(&self, frame: Vec<u8>) {
+        if let Err(mpsc::error::TrySendError::Full(_)) = self.tx.try_send(frame) {
+            warn!("{}: send queue full, dropping frame", self.label());
+        }
+        // Closed channel (client disconnected) is silently ignored — the session
+        // will be cleaned up when the client handler task exits.
+    }
+}