S210: PG-46 — bounded BTSP handshake timeouts

Root cause: JSON-line BTSP relay made two sequential BearDog RPCs
(btsp.session.create + btsp.session.verify) with no timeout. Slow
BearDog responses caused the handshake to consume most of a client's
time budget, leaving the first JSON-RPC read to return empty/timeout.

Fix:
- relay_json_line_handshake() now wrapped in total budget (5s default,
  override via BTSP_HANDSHAKE_TIMEOUT_SECS)
- Each BearDog RPC call uses call_with_timeout (3s default, override
  via BTSP_RPC_TIMEOUT_SECS)
- New BtspJsonLineError::Timeout variant for clear error reporting
- New UnixJsonRpcClient::call_with_timeout method
- Constants in timeouts.rs, env-var keys in socket_env.rs

7,842 lib-only tests, 0 failures, clippy clean (-D warnings), fmt clean.

Made-with: Cursor

Author: westgate

DEBT.md

@@ -1,13 +1,21 @@
 # Active Technical Debt Register
 
-**Date**: April 2026 — S209
+**Date**: April 2026 — S210
 **Philosophy**: Math is universal, precision is silicon. Workarounds are
 short-term solutions that increase debt. We aim to solve deep debt over
 iterations, evolving toward vendor-agnostic, capability-based solutions—
 with production stubs surfacing typed configuration errors and capability
 guidance, and auth policy driven by explicit environment configuration
 where applicable.
 
+**S210 (PG-46: BTSP Handshake Timeout)**:
+Added bounded timeouts to JSON-line BTSP handshake relay. Total handshake
+budget: 5s default (`BTSP_HANDSHAKE_TIMEOUT_SECS`). Per-BearDog-RPC budget:
+3s default (`BTSP_RPC_TIMEOUT_SECS`). `UnixJsonRpcClient::call_with_timeout`
+added. `BtspJsonLineError::Timeout` variant for clear error reporting.
+Resolves PG-46 (short-timeout reads returning empty responses due to
+unbounded handshake latency). **7,842 lib-only** tests, 0 failures.
+
 **S209 (Deep Debt — Lint Reason + Dep Unification + Auth Capability)**:
 Completed comprehensive lint evolution: all remaining crate-level `#![allow]`
 attrs evolved to include `reason =` (7 embedded/neuromorphic/native/testing

NEXT_STEPS.md

@@ -1,8 +1,8 @@
 # ToadStool -- Next Steps
 
-**Updated**: April 2026 — S209 (Deep Debt — Lint Reason + Dep Unification + Auth Capability)
-**Status**: Production-grade | Rust edition **2024** (MSRV 1.85) | **AGPL-3.0-or-later** | **All quality gates green** | **7,842 lib-only** tests verified (20,000+ workspace, 0 failures) | **~65 JSON-RPC methods** | Wire Standard L3 (partial) | Zero C FFI deps (ecoBin v3.0) | **Zero production panics/expects** | IPC-first | workspace `unsafe_code = "deny"`, **41 crates `forbid`** | **49 unsafe blocks** (all in hw containment, all SAFETY-documented) | **0 production TODOs** | **rustix 1.x workspace-wide** | **capability-based primal references (no hardcoded names)** | **`async-trait` DEPRECATED** (banned in `deny.toml`) | **`deny.toml` ring + async-trait + zstd-sys bans active** | **env centralized via config structs** | **real Linux sandbox (rustix)** | **real resource metrics (cgroup v2/proc)** | **plugin loading (libloading)** | **binary tarpc framing (MessagePack)** | **BTSP JSON-line relay (Phase 45c)** | **Display Phase 2 (petalTongue IPC)** | **Encrypted compute dispatch (Phase 55)** | **All lint attrs with reason (S209)** | **test-mocks off by default (S206)** | **Self-registration with Songbird (S207)** | **Auth issuer capability-based (S209)**
-**Latest**: S209 — Deep Debt — Lint Reason + Dep Unification + Auth Capability: All remaining crate-level `#![allow]` attrs given `reason =` (7 crates). ~30 production `#[expect(deprecated)]`/`#[allow(deprecated)]` upgraded with `reason =`. 23 Cargo.toml files unified to workspace deps (`sha2`, `serde_json`, `tracing`, `thiserror`, `tracing-subscriber`, `tokio-test`). Auth backend: hardcoded `well_known::BEARDOG` issuer fallback → `capabilities::CRYPTO`. Stale python feature flags removed. **7,842 lib-only** tests, 0 failures, clippy clean, fmt clean.
+**Updated**: April 2026 — S210 (PG-46: BTSP Handshake Timeout)
+**Status**: Production-grade | Rust edition **2024** (MSRV 1.85) | **AGPL-3.0-or-later** | **All quality gates green** | **7,842 lib-only** tests verified (20,000+ workspace, 0 failures) | **~65 JSON-RPC methods** | Wire Standard L3 (partial) | Zero C FFI deps (ecoBin v3.0) | **Zero production panics/expects** | IPC-first | workspace `unsafe_code = "deny"`, **41 crates `forbid`** | **49 unsafe blocks** (all in hw containment, all SAFETY-documented) | **0 production TODOs** | **rustix 1.x workspace-wide** | **capability-based primal references (no hardcoded names)** | **`async-trait` DEPRECATED** (banned in `deny.toml`) | **`deny.toml` ring + async-trait + zstd-sys bans active** | **BTSP handshake bounded** (5s default, PG-46, S210) | **All lint attrs with reason (S209)** | **Auth issuer capability-based (S209)** | **Self-registration with Songbird (S207)** | **Encrypted compute dispatch (Phase 55)** | **Display Phase 2 (petalTongue IPC)** | **BTSP JSON-line relay (Phase 45c)**
+**Latest**: S210 — PG-46: BTSP Handshake Timeout. Added bounded timeouts to JSON-line BTSP handshake relay: 5s total budget (`BTSP_HANDSHAKE_TIMEOUT_SECS`), 3s per BearDog RPC (`BTSP_RPC_TIMEOUT_SECS`). `UnixJsonRpcClient::call_with_timeout` added. `BtspJsonLineError::Timeout` variant. Resolves short-timeout reads returning empty responses. **7,842 lib-only** tests, 0 failures, clippy clean, fmt clean.
 
 ---
 

crates/core/common/src/btsp/json_line.rs

@@ -2,6 +2,7 @@
 //! JSON newline BTSP handshake relay via BearDog JSON-RPC.
 
 use std::path::PathBuf;
+use std::time::Duration;
 
 use base64::Engine;
 use serde::Deserialize;
@@ -10,6 +11,8 @@ use thiserror::Error;
 use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
 
 use crate::ToadStoolError;
+use crate::constants::timeouts;
+use crate::interned_strings::socket_env;
 use crate::unix_jsonrpc::UnixJsonRpcClient;
 
 use super::types::BtspCipher;
@@ -41,6 +44,10 @@ pub enum BtspJsonLineError {
     /// Protocol violation (version, missing field, etc.).
     #[error("BTSP JSON-line protocol: {0}")]
     Protocol(String),
+
+    /// Handshake or RPC call exceeded its timeout budget.
+    #[error("BTSP JSON-line timeout: {0}")]
+    Timeout(String),
 }
 
 impl From<ToadStoolError> for BtspJsonLineError {
@@ -49,6 +56,20 @@ impl From<ToadStoolError> for BtspJsonLineError {
     }
 }
 
+fn handshake_timeout() -> Duration {
+    std::env::var(socket_env::BTSP_HANDSHAKE_TIMEOUT_SECS)
+        .ok()
+        .and_then(|v| v.parse::<u64>().ok())
+        .map_or(timeouts::BTSP_HANDSHAKE_TIMEOUT, Duration::from_secs)
+}
+
+fn rpc_timeout() -> Duration {
+    std::env::var(socket_env::BTSP_RPC_TIMEOUT_SECS)
+        .ok()
+        .and_then(|v| v.parse::<u64>().ok())
+        .map_or(timeouts::BTSP_RPC_TIMEOUT, Duration::from_secs)
+}
+
 /// Check if a JSON line looks like a BTSP ClientHello.
 ///
 /// The line must parse as JSON and carry `"protocol": "btsp"` (spacing-insensitive via serde).
@@ -199,12 +220,38 @@ async fn require_str_line<S: AsyncWrite + Unpin>(
 /// 5. Call BearDog `btsp.session.verify` with session_token, response, client_ephemeral_pub, preferred_cipher
 /// 6. Send HandshakeComplete JSON line
 ///
+/// The entire handshake is bounded by `BTSP_HANDSHAKE_TIMEOUT` (default 5s,
+/// override via `BTSP_HANDSHAKE_TIMEOUT_SECS`). Each BearDog RPC call is
+/// individually bounded by `BTSP_RPC_TIMEOUT` (default 3s, override via
+/// `BTSP_RPC_TIMEOUT_SECS`).
+///
 /// On error at any step, sends an error JSON line and returns `Err`.
 pub async fn relay_json_line_handshake<S: AsyncRead + AsyncWrite + Unpin>(
     stream: &mut S,
     first_line: &str,
     family_seed: &str,
     security_socket: &str,
+) -> Result<BtspSessionInfo, BtspJsonLineError> {
+    let budget = handshake_timeout();
+    let Ok(result) = tokio::time::timeout(
+        budget,
+        relay_json_line_handshake_inner(stream, first_line, family_seed, security_socket),
+    )
+    .await
+    else {
+        let msg = format!("BTSP handshake exceeded {budget:?} budget");
+        tracing::warn!(target: "btsp", "{msg}");
+        let _ = send_error_line(stream, &msg).await;
+        return Err(BtspJsonLineError::Timeout(msg));
+    };
+    result
+}
+
+async fn relay_json_line_handshake_inner<S: AsyncRead + AsyncWrite + Unpin>(
+    stream: &mut S,
+    first_line: &str,
+    family_seed: &str,
+    security_socket: &str,
 ) -> Result<BtspSessionInfo, BtspJsonLineError> {
     tracing::info!(target: "btsp", "JSON-line BTSP: parsing ClientHello");
 
@@ -235,9 +282,13 @@ pub async fn relay_json_line_handshake<S: AsyncRead + AsyncWrite + Unpin>(
     tracing::info!(target: "btsp", "JSON-line BTSP: calling btsp.session.create");
 
     let rpc = UnixJsonRpcClient::new(security_socket);
+    let rpc_budget = rpc_timeout();
     let family_seed_b64 = base64::engine::general_purpose::STANDARD.encode(family_seed.as_bytes());
     let create_params = serde_json::json!({ "family_seed": family_seed_b64 });
-    let create_result: Value = match rpc.call("btsp.session.create", create_params).await {
+    let create_result: Value = match rpc
+        .call_with_timeout("btsp.session.create", create_params, rpc_budget)
+        .await
+    {
         Ok(v) => v,
         Err(e) => {
             let msg = e.to_string();
@@ -297,7 +348,10 @@ pub async fn relay_json_line_handshake<S: AsyncRead + AsyncWrite + Unpin>(
         "client_ephemeral_pub": hello.client_ephemeral_pub,
         "preferred_cipher": cr.preferred_cipher,
     });
-    let verify_result: Value = match rpc.call("btsp.session.verify", verify_params).await {
+    let verify_result: Value = match rpc
+        .call_with_timeout("btsp.session.verify", verify_params, rpc_budget)
+        .await
+    {
         Ok(v) => v,
         Err(e) => {
             let msg = e.to_string();

crates/core/common/src/constants/timeouts.rs

@@ -127,6 +127,23 @@ pub const VERIFICATION_PHASE_TIMEOUT: Duration = Duration::from_secs(5);
 /// Total zero-config bootstrap target (60 seconds)
 pub const ZERO_CONFIG_TARGET: Duration = Duration::from_secs(60);
 
+// ============================================================================
+// BTSP Handshake Timeouts (PG-46)
+// ============================================================================
+
+/// Total BTSP handshake budget (5 seconds).
+///
+/// Covers the full 4-step JSON-line relay including both BearDog RPCs.
+/// Clients using <10s read timeouts previously hit empty responses because
+/// the handshake had no upper bound. Override via `BTSP_HANDSHAKE_TIMEOUT_SECS`.
+pub const BTSP_HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Per-RPC timeout for BearDog calls during BTSP handshake (3 seconds).
+///
+/// Applied individually to `btsp.session.create` and `btsp.session.verify`.
+/// Override via `BTSP_RPC_TIMEOUT_SECS`.
+pub const BTSP_RPC_TIMEOUT: Duration = Duration::from_secs(3);
+
 // ============================================================================
 // Authentication Timeouts
 // ============================================================================

crates/core/common/src/interned_strings/socket_env.rs

@@ -127,6 +127,10 @@ pub const TOADSTOOL_TCP_BIND_ADDRESS: &str = "TOADSTOOL_TCP_BIND_ADDRESS";
 /// Idle timeout (seconds) for Pure JSON-RPC TCP connections.
 pub const TOADSTOOL_TCP_IDLE_TIMEOUT_SECS: &str = "TOADSTOOL_TCP_IDLE_TIMEOUT_SECS";
 pub const TOADSTOOL_STANDALONE: &str = "TOADSTOOL_STANDALONE";
+/// Override total BTSP handshake timeout (seconds). Default: 5.
+pub const BTSP_HANDSHAKE_TIMEOUT_SECS: &str = "BTSP_HANDSHAKE_TIMEOUT_SECS";
+/// Override per-RPC timeout for BearDog calls during BTSP (seconds). Default: 3.
+pub const BTSP_RPC_TIMEOUT_SECS: &str = "BTSP_RPC_TIMEOUT_SECS";
 
 pub const TOADSTOOL_PORT: &str = "TOADSTOOL_PORT";
 pub const TOADSTOOL_REQUEST_TIMEOUT: &str = "TOADSTOOL_REQUEST_TIMEOUT";

crates/core/common/src/unix_jsonrpc_client.rs

@@ -174,6 +174,29 @@ impl UnixJsonRpcClient {
             .ok_or_else(|| ToadStoolError::network("JSON-RPC response missing result"))
     }
 
+    /// Call JSON-RPC method with a wall-clock timeout.
+    ///
+    /// Wraps [`call`](Self::call) in `tokio::time::timeout`.
+    ///
+    /// # Errors
+    ///
+    /// Returns error if the timeout elapses or the inner call fails.
+    pub async fn call_with_timeout(
+        &self,
+        method: &str,
+        params: Value,
+        timeout: std::time::Duration,
+    ) -> ToadStoolResult<Value> {
+        tokio::time::timeout(timeout, self.call(method, params))
+            .await
+            .map_err(|_| {
+                ToadStoolError::network(format!(
+                    "RPC call {method} to {} timed out after {timeout:?}",
+                    self.socket_path.display()
+                ))
+            })?
+    }
+
     /// Call JSON-RPC method and deserialize response
     ///
     /// ## Type Safety