feat(remote): add network-efficient thin client transport

Add SSH stdio remote attach, negotiate terminal-ANSI render encoding, move blit encoding server-side for remote clients, and split control/render writer delivery for safer backpressure.

Fixes #76

8 files changed, 95 insertions, 71 deletions

diff --git a/tests/api_ping.rs b/tests/api_ping.rs
index b0411559..bcb97ab3 100644
--- a/tests/api_ping.rs
+++ b/tests/api_ping.rs
@@ -223,7 +223,7 @@ fn ping_over_socket_returns_version() {
     assert_eq!(value["id"], "req_1");
     assert_eq!(value["result"]["type"], "pong");
     assert_eq!(value["result"]["version"], env!("CARGO_PKG_VERSION"));
-    assert_eq!(value["result"]["protocol"], 3);
+    assert_eq!(value["result"]["protocol"], 4);
 
     cleanup_spawned_herdr(child, base);
 }
diff --git a/tests/cli_wrapper.rs b/tests/cli_wrapper.rs
index a68fcb6c..de0d141f 100644
--- a/tests/cli_wrapper.rs
+++ b/tests/cli_wrapper.rs
@@ -871,7 +871,7 @@ fn status_commands_report_client_and_server_versions() {
         "stdout: {full_stdout}"
     );
     assert!(
-        full_stdout.contains("  protocol: 3"),
+        full_stdout.contains("  protocol: 4"),
         "stdout: {full_stdout}"
     );
     assert!(full_stdout.contains("server:\n"), "stdout: {full_stdout}");
@@ -904,7 +904,7 @@ fn status_commands_report_client_and_server_versions() {
         "stdout: {server_stdout}"
     );
     assert!(
-        server_stdout.contains("protocol: 3"),
+        server_stdout.contains("protocol: 4"),
         "stdout: {server_stdout}"
     );
 
@@ -916,7 +916,7 @@ fn status_commands_report_client_and_server_versions() {
         "stdout: {client_stdout}"
     );
     assert!(
-        client_stdout.contains("protocol: 3"),
+        client_stdout.contains("protocol: 4"),
         "stdout: {client_stdout}"
     );
     assert!(
@@ -1666,11 +1666,17 @@ fn pane_shell_gets_herdr_socket_and_pane_env() {
     assert!(ran.status.success());
 
     let deadline = Instant::now() + Duration::from_secs(3);
-    while Instant::now() < deadline && !env_capture.exists() {
+    let mut text = String::new();
+    while Instant::now() < deadline {
+        if env_capture.exists() {
+            text = fs::read_to_string(&env_capture).unwrap();
+            if text.contains(&socket_path.display().to_string()) && text.contains("p_") {
+                break;
+            }
+        }
         thread::sleep(Duration::from_millis(25));
     }
     assert!(env_capture.exists(), "env capture file was not created");
-    let text = fs::read_to_string(&env_capture).unwrap();
     assert!(
         text.contains(&socket_path.display().to_string()),
         "env file was: {text:?}"
diff --git a/tests/client_mode.rs b/tests/client_mode.rs
index f35ee301..7b6639f9 100644
--- a/tests/client_mode.rs
+++ b/tests/client_mode.rs
@@ -250,8 +250,8 @@ fn client_connects_and_receives_frame() {
     // Connect and handshake.
     let mut stream = UnixStream::connect(&client_socket).expect("should connect to client socket");
     let (version, error) =
-        client_handshake(&mut stream, 3, 80, 24).expect("handshake should succeed");
-    assert_eq!(version, 3, "server should report protocol version 3");
+        client_handshake(&mut stream, 4, 80, 24).expect("handshake should succeed");
+    assert_eq!(version, 4, "server should report protocol version 4");
     assert!(
         error.is_none(),
         "handshake should not have error: {:?}",
@@ -330,8 +330,8 @@ fn client_sees_headless_startup_config_diagnostic() {
 
     let mut stream = UnixStream::connect(&client_socket).expect("should connect to client socket");
     let (version, error) =
-        client_handshake(&mut stream, 3, 80, 24).expect("handshake should succeed");
-    assert_eq!(version, 3);
+        client_handshake(&mut stream, 4, 80, 24).expect("handshake should succeed");
+    assert_eq!(version, 4);
     assert!(error.is_none(), "{:?}", error);
 
     stream
@@ -379,8 +379,8 @@ fn client_input_forwarded_to_pane() {
     // Connect and handshake.
     let mut stream = UnixStream::connect(&client_socket).expect("should connect to client socket");
     let (version, error) =
-        client_handshake(&mut stream, 3, 80, 24).expect("handshake should succeed");
-    assert_eq!(version, 3);
+        client_handshake(&mut stream, 4, 80, 24).expect("handshake should succeed");
+    assert_eq!(version, 4);
     assert!(error.is_none(), "{:?}", error);
 
     // Send an Input message containing "echo hello\n".
@@ -433,8 +433,8 @@ fn client_resize_sends_message() {
     // Connect and handshake.
     let mut stream = UnixStream::connect(&client_socket).expect("should connect to client socket");
     let (version, error) =
-        client_handshake(&mut stream, 3, 80, 24).expect("handshake should succeed");
-    assert_eq!(version, 3);
+        client_handshake(&mut stream, 4, 80, 24).expect("handshake should succeed");
+    assert_eq!(version, 4);
     assert!(error.is_none(), "{:?}", error);
 
     // Drain the initial frame(s).
@@ -490,8 +490,8 @@ fn server_shutdown_sends_message_to_client() {
     // Connect and handshake.
     let mut stream = UnixStream::connect(&client_socket).expect("should connect to client socket");
     let (version, error) =
-        client_handshake(&mut stream, 3, 80, 24).expect("handshake should succeed");
-    assert_eq!(version, 3);
+        client_handshake(&mut stream, 4, 80, 24).expect("handshake should succeed");
+    assert_eq!(version, 4);
     assert!(error.is_none(), "{:?}", error);
 
     // Send SIGINT so the server takes the graceful shutdown path and
@@ -513,7 +513,7 @@ fn server_shutdown_sends_message_to_client() {
     while Instant::now() < deadline {
         match read_server_message(&mut stream) {
             Ok((variant, _)) => {
-                if variant == 2 {
+                if variant == 3 {
                     saw_shutdown = true;
                     break;
                 }
@@ -717,8 +717,8 @@ fn client_receives_frame_after_pane_output() {
     // Connect and handshake.
     let mut stream = UnixStream::connect(&client_socket).expect("should connect to client socket");
     let (version, error) =
-        client_handshake(&mut stream, 3, 80, 24).expect("handshake should succeed");
-    assert_eq!(version, 3);
+        client_handshake(&mut stream, 4, 80, 24).expect("handshake should succeed");
+    assert_eq!(version, 4);
     assert!(error.is_none(), "{:?}", error);
 
     // Read the initial frame (server renders immediately on client connect).
@@ -771,8 +771,8 @@ fn navigate_mode_keybind_dispatch_in_server() {
     // Connect and handshake.
     let mut stream = UnixStream::connect(&client_socket).expect("should connect to client socket");
     let (version, error) =
-        client_handshake(&mut stream, 3, 80, 24).expect("handshake should succeed");
-    assert_eq!(version, 3);
+        client_handshake(&mut stream, 4, 80, 24).expect("handshake should succeed");
+    assert_eq!(version, 4);
     assert!(error.is_none(), "{:?}", error);
 
     // Drain initial frames.
@@ -889,8 +889,8 @@ fn graceful_shutdown_sends_server_shutdown_to_client() {
     // Connect and handshake.
     let mut stream = UnixStream::connect(&client_socket).expect("should connect to client socket");
     let (version, error) =
-        client_handshake(&mut stream, 3, 80, 24).expect("handshake should succeed");
-    assert_eq!(version, 3);
+        client_handshake(&mut stream, 4, 80, 24).expect("handshake should succeed");
+    assert_eq!(version, 4);
     assert!(error.is_none(), "{:?}", error);
 
     // Drain initial frame(s).
@@ -906,7 +906,7 @@ fn graceful_shutdown_sends_server_shutdown_to_client() {
         }
     }
 
-    // The client should receive a ServerShutdown message (variant 2)
+    // The client should receive a ServerShutdown message (variant 3)
     // before the connection is closed, not just an abrupt EOF.
     stream
         .set_read_timeout(Some(Duration::from_secs(5)))
@@ -915,8 +915,8 @@ fn graceful_shutdown_sends_server_shutdown_to_client() {
     match result {
         Ok((variant, _payload)) => {
             assert_eq!(
-                variant, 2,
-                "expected ServerShutdown (variant 2), got variant {variant}"
+                variant, 3,
+                "expected ServerShutdown (variant 3), got variant {variant}"
             );
         }
         Err(e) => {
@@ -987,8 +987,8 @@ fn client_receives_notify_on_agent_state_change() {
     // Connect as a client and perform handshake.
     let mut stream = UnixStream::connect(&client_socket).expect("should connect");
     let (version, error) =
-        client_handshake(&mut stream, 3, 80, 24).expect("handshake should succeed");
-    assert_eq!(version, 3);
+        client_handshake(&mut stream, 4, 80, 24).expect("handshake should succeed");
+    assert_eq!(version, 4);
     assert!(error.is_none(), "{:?}", error);
 
     // Drain initial frame(s).
@@ -1039,8 +1039,8 @@ fn client_receives_notify_on_agent_state_change() {
     let mut report_response = String::new();
     report_reader.read_line(&mut report_response).unwrap();
 
-    // Read messages from the client stream and look for Notify (variant 3).
-    // Notify = ServerMessage variant index 3 (after Welcome=0, Frame=1, ServerShutdown=2).
+    // Read messages from the client stream and look for Notify (variant 4).
+    // Notify = ServerMessage variant index 4 (after Welcome=0, Frame=1, Terminal=2, ServerShutdown=3).
     stream
         .set_read_timeout(Some(Duration::from_secs(5)))
         .unwrap();
@@ -1049,7 +1049,7 @@ fn client_receives_notify_on_agent_state_change() {
     while Instant::now() < deadline {
         match read_server_message(&mut stream) {
             Ok((variant, _payload)) => {
-                if variant == 3 {
+                if variant == 4 {
                     // ServerMessage::Notify — found it!
                     found_notify = true;
                     break;
@@ -1135,7 +1135,7 @@ fn client_receives_notify_on_agent_state_change() {
     while Instant::now() < deadline {
         match read_server_message(&mut stream) {
             Ok((variant, _payload)) => {
-                if variant == 3 {
+                if variant == 4 {
                     // Found a Notify message — that's good enough.
                     // The test already verified the Blocked→Notify path above.
                     found_done_notify = true;
diff --git a/tests/cross_area.rs b/tests/cross_area.rs
index 0740a7dd..db7f5b1f 100644
--- a/tests/cross_area.rs
+++ b/tests/cross_area.rs
@@ -416,6 +416,7 @@ fn client_handshake(stream: &mut UnixStream, version: u32, cols: u16, rows: u16)
     payload.extend_from_slice(&encode_varint_u32(version));
     payload.extend_from_slice(&encode_varint_u16(cols));
     payload.extend_from_slice(&encode_varint_u16(rows));
+    payload.extend_from_slice(&encode_varint_u32(0)); // RenderEncoding::SemanticFrame
 
     stream
         .write_all(&frame_message(&payload))
@@ -443,6 +444,10 @@ fn client_handshake(stream: &mut UnixStream, version: u32, cols: u16, rows: u16)
         decode_varint_u32(&welcome_payload, offset).expect("decode version");
     offset += consumed;
 
+    let (_encoding, consumed) =
+        decode_varint_u32(&welcome_payload, offset).expect("decode render encoding");
+    offset += consumed;
+
     let option_tag = *welcome_payload
         .get(offset)
         .expect("welcome payload should contain Option tag");
@@ -669,7 +674,7 @@ fn cross_area_detach_and_reattach_preserves_state() {
 
     // Local attach (client A).
     let mut client_a = UnixStream::connect(&client_socket).expect("client A should connect");
-    client_handshake(&mut client_a, 3, 100, 30);
+    client_handshake(&mut client_a, 4, 100, 30);
     assert!(wait_for_frame(&mut client_a, Duration::from_secs(2)));
 
     // Use herdr: create a workspace and write output into its pane.
@@ -706,7 +711,7 @@ fn cross_area_detach_and_reattach_preserves_state() {
 
     // Reattach from another terminal/session (client B).
     let mut client_b = UnixStream::connect(&client_socket).expect("client B should connect");
-    client_handshake(&mut client_b, 3, 80, 24);
+    client_handshake(&mut client_b, 4, 80, 24);
     assert!(
         wait_for_frame(&mut client_b, Duration::from_secs(5)),
         "reattached client should receive frame"
@@ -762,7 +767,7 @@ fn cross_area_agent_process_survives_detach_and_reattach() {
     wait_for_socket(&client_socket, Duration::from_secs(10));
 
     let mut client_a = UnixStream::connect(&client_socket).expect("client A should connect");
-    client_handshake(&mut client_a, 3, 100, 30);
+    client_handshake(&mut client_a, 4, 100, 30);
     assert!(wait_for_frame(&mut client_a, Duration::from_secs(2)));
 
     let created = workspace_create(&api_socket, "agent-persist");
@@ -815,7 +820,7 @@ fn cross_area_agent_process_survives_detach_and_reattach() {
 
     // Reattach and ensure client-side state reflects the persisted working status.
     let mut client_b = UnixStream::connect(&client_socket).expect("client B should connect");
-    client_handshake(&mut client_b, 3, 80, 24);
+    client_handshake(&mut client_b, 4, 80, 24);
     let saw_working_on_client =
         wait_for_frame_matching(&mut client_b, Duration::from_secs(5), |frame| {
             frame_contains_text(frame, "working")
@@ -860,7 +865,7 @@ fn cross_area_client_and_api_workspace_views_are_consistent() {
     wait_for_socket(&client_socket, Duration::from_secs(10));
 
     let mut client = UnixStream::connect(&client_socket).expect("client should connect");
-    client_handshake(&mut client, 3, 100, 30);
+    client_handshake(&mut client, 4, 100, 30);
     assert!(wait_for_frame(&mut client, Duration::from_secs(2)));
     drain_server_messages(&mut client, Duration::from_millis(300));
 
@@ -923,9 +928,9 @@ fn cross_area_two_clients_shared_view_and_single_detach_stability() {
     wait_for_socket(&client_socket, Duration::from_secs(10));
 
     let mut client_a = UnixStream::connect(&client_socket).expect("client A should connect");
-    client_handshake(&mut client_a, 3, 110, 30);
+    client_handshake(&mut client_a, 4, 110, 30);
     let mut client_b = UnixStream::connect(&client_socket).expect("client B should connect");
-    client_handshake(&mut client_b, 3, 100, 30);
+    client_handshake(&mut client_b, 4, 100, 30);
 
     assert!(wait_for_frame(&mut client_a, Duration::from_secs(2)));
     assert!(wait_for_frame(&mut client_b, Duration::from_secs(2)));
@@ -1091,7 +1096,7 @@ fn cross_area_server_kill_then_restart_and_reconnect() {
 
     let mut reconnect_client =
         UnixStream::connect(&client_socket).expect("new client should connect after restart");
-    client_handshake(&mut reconnect_client, 3, 80, 24);
+    client_handshake(&mut reconnect_client, 4, 80, 24);
     assert!(
         wait_for_frame(&mut reconnect_client, Duration::from_secs(5)),
         "new client should receive frame after restart"
diff --git a/tests/detach_reattach.rs b/tests/detach_reattach.rs
index 259cf350..519c2ca2 100644
--- a/tests/detach_reattach.rs
+++ b/tests/detach_reattach.rs
@@ -276,8 +276,8 @@ fn navigate_q_detaches_client_and_server_persists() {
     // Connect and handshake.
     let mut stream = UnixStream::connect(&client_socket).expect("should connect to client socket");
     let (version, error) =
-        client_handshake(&mut stream, 3, 80, 24).expect("handshake should succeed");
-    assert_eq!(version, 3);
+        client_handshake(&mut stream, 4, 80, 24).expect("handshake should succeed");
+    assert_eq!(version, 4);
     assert!(error.is_none(), "{:?}", error);
 
     // Drain initial frames.
@@ -338,8 +338,8 @@ fn explicit_detach_message_causes_clean_disconnect() {
     // Connect and handshake.
     let mut stream = UnixStream::connect(&client_socket).expect("should connect");
     let (version, error) =
-        client_handshake(&mut stream, 3, 80, 24).expect("handshake should succeed");
-    assert_eq!(version, 3);
+        client_handshake(&mut stream, 4, 80, 24).expect("handshake should succeed");
+    assert_eq!(version, 4);
     assert!(error.is_none(), "{:?}", error);
 
     // Drain initial frames.
@@ -397,8 +397,8 @@ fn reattach_after_detach_shows_current_state() {
     // --- Client A ---
     let mut stream_a = UnixStream::connect(&client_socket).expect("client A should connect");
     let (version, error) =
-        client_handshake(&mut stream_a, 3, 80, 24).expect("handshake should succeed");
-    assert_eq!(version, 3);
+        client_handshake(&mut stream_a, 4, 80, 24).expect("handshake should succeed");
+    assert_eq!(version, 4);
     assert!(error.is_none(), "{:?}", error);
 
     // Drain initial frames.
@@ -436,8 +436,8 @@ fn reattach_after_detach_shows_current_state() {
     // --- Client B (reattach) ---
     let mut stream_b = UnixStream::connect(&client_socket).expect("client B should connect");
     let (version, error) =
-        client_handshake(&mut stream_b, 3, 80, 24).expect("handshake should succeed");
-    assert_eq!(version, 3);
+        client_handshake(&mut stream_b, 4, 80, 24).expect("handshake should succeed");
+    assert_eq!(version, 4);
     assert!(
         error.is_none(),
         "reattach handshake should succeed: {:?}",
@@ -516,8 +516,8 @@ fn processes_survive_during_and_after_detach() {
     // Connect and handshake.
     let mut stream = UnixStream::connect(&client_socket).expect("should connect");
     let (version, error) =
-        client_handshake(&mut stream, 3, 80, 24).expect("handshake should succeed");
-    assert_eq!(version, 3);
+        client_handshake(&mut stream, 4, 80, 24).expect("handshake should succeed");
+    assert_eq!(version, 4);
     assert!(error.is_none(), "{:?}", error);
 
     // Drain initial frames.
@@ -555,8 +555,8 @@ fn processes_survive_during_and_after_detach() {
     // Reattach — verify we can connect and receive a frame.
     let mut stream_b = UnixStream::connect(&client_socket).expect("should reattach");
     let (version, error) =
-        client_handshake(&mut stream_b, 3, 80, 24).expect("reattach handshake should succeed");
-    assert_eq!(version, 3);
+        client_handshake(&mut stream_b, 4, 80, 24).expect("reattach handshake should succeed");
+    assert_eq!(version, 4);
     assert!(error.is_none(), "{:?}", error);
 
     // Verify the reattached client receives a frame.
@@ -604,8 +604,8 @@ fn server_persists_after_client_connection_drop() {
     // Connect and handshake.
     let mut stream = UnixStream::connect(&client_socket).expect("should connect");
     let (version, error) =
-        client_handshake(&mut stream, 3, 80, 24).expect("handshake should succeed");
-    assert_eq!(version, 3);
+        client_handshake(&mut stream, 4, 80, 24).expect("handshake should succeed");
+    assert_eq!(version, 4);
     assert!(error.is_none(), "{:?}", error);
 
     // Drain initial frames.
@@ -631,8 +631,8 @@ fn server_persists_after_client_connection_drop() {
     // Reattach — verify we can connect and handshake again.
     let mut stream_b = UnixStream::connect(&client_socket).expect("should reattach");
     let (version, error) =
-        client_handshake(&mut stream_b, 3, 80, 24).expect("reattach handshake should succeed");
-    assert_eq!(version, 3);
+        client_handshake(&mut stream_b, 4, 80, 24).expect("reattach handshake should succeed");
+    assert_eq!(version, 4);
     assert!(error.is_none(), "reattach should succeed: {:?}", error);
 
     cleanup_spawned_herdr(spawned, base);
@@ -653,8 +653,8 @@ fn detached_output_preserves_last_attached_pty_size() {
 
     let mut stream = UnixStream::connect(&client_socket).expect("client should connect");
     let (version, error) =
-        client_handshake(&mut stream, 3, 120, 40).expect("handshake should succeed");
-    assert_eq!(version, 3);
+        client_handshake(&mut stream, 4, 120, 40).expect("handshake should succeed");
+    assert_eq!(version, 4);
     assert!(error.is_none(), "{:?}", error);
     drain_messages(&mut stream);
 
@@ -722,8 +722,8 @@ fn output_accumulated_while_detached_visible_on_reattach() {
     // Connect and handshake client A.
     let mut stream_a = UnixStream::connect(&client_socket).expect("client A should connect");
     let (version, error) =
-        client_handshake(&mut stream_a, 3, 80, 24).expect("handshake should succeed");
-    assert_eq!(version, 3);
+        client_handshake(&mut stream_a, 4, 80, 24).expect("handshake should succeed");
+    assert_eq!(version, 4);
     assert!(error.is_none(), "{:?}", error);
 
     // Detach client A immediately.
@@ -780,8 +780,8 @@ fn output_accumulated_while_detached_visible_on_reattach() {
     // --- Client B (reattach) ---
     let mut stream_b = UnixStream::connect(&client_socket).expect("client B should connect");
     let (version, error) =
-        client_handshake(&mut stream_b, 3, 80, 24).expect("reattach handshake should succeed");
-    assert_eq!(version, 3);
+        client_handshake(&mut stream_b, 4, 80, 24).expect("reattach handshake should succeed");
+    assert_eq!(version, 4);
     assert!(error.is_none(), "{:?}", error);
 
     // Client B should receive a frame with the current state.
diff --git a/tests/multi_client.rs b/tests/multi_client.rs
index f65538b4..3294c98b 100644
--- a/tests/multi_client.rs
+++ b/tests/multi_client.rs
@@ -495,6 +495,7 @@ fn client_handshake(
             &encode_varint_u32(version),
             &encode_varint_u16(cols),
             &encode_varint_u16(rows),
+            &encode_varint_u32(0), // RenderEncoding::SemanticFrame
         ],
     );
     stream
@@ -519,6 +520,9 @@ fn client_handshake(
     let (_server_version, consumed) = decode_varint_u32(&payload, offset)?;
     offset += consumed;
 
+    let (_encoding, consumed) = decode_varint_u32(&payload, offset)?;
+    offset += consumed;
+
     if offset >= payload.len() {
         return Err("payload too short for Welcome.error option tag".into());
     }
@@ -542,7 +546,7 @@ fn client_handshake(
 
 fn connect_raw_client(client_socket: &Path, cols: u16, rows: u16) -> UnixStream {
     let mut stream = UnixStream::connect(client_socket).expect("should connect to client socket");
-    client_handshake(&mut stream, 3, cols, rows).expect("handshake should succeed");
+    client_handshake(&mut stream, 4, cols, rows).expect("handshake should succeed");
     stream
 }
 
diff --git a/tests/server_headless.rs b/tests/server_headless.rs
index 687b886b..33a3fa7f 100644
--- a/tests/server_headless.rs
+++ b/tests/server_headless.rs
@@ -169,6 +169,7 @@ fn client_handshake(
             &encode_varint_u32(version),
             &encode_varint_u16(cols),
             &encode_varint_u16(rows),
+            &encode_varint_u32(0), // RenderEncoding::SemanticFrame
         ],
     );
     let framed = frame_message(&hello_payload);
@@ -310,6 +311,10 @@ fn decode_welcome(payload: &[u8]) -> Result<(u32, Option<String>), String> {
     let (version, consumed) = decode_varint_u32(payload, offset)?;
     offset += consumed;
 
+    // encoding: RenderEncoding
+    let (_encoding, consumed) = decode_varint_u32(payload, offset)?;
+    offset += consumed;
+
     // error: Option<String> — discriminant is always 1 byte
     if offset >= payload.len() {
         return Err("payload too short for Option tag".into());
@@ -576,11 +581,11 @@ fn client_handshake_succeeds() {
     // Connect to the client socket and perform a handshake.
     let mut stream = UnixStream::connect(&client_socket).expect("should connect to client socket");
 
-    // Send Hello with version 2, 80 cols, 24 rows.
+    // Send Hello with version 4, 80 cols, 24 rows.
     let (version, error) =
-        client_handshake(&mut stream, 3, 80, 24).expect("handshake should succeed");
+        client_handshake(&mut stream, 4, 80, 24).expect("handshake should succeed");
 
-    assert_eq!(version, 3, "server should report protocol version 3");
+    assert_eq!(version, 4, "server should report protocol version 4");
     assert!(
         error.is_none(),
         "handshake should not have an error: {:?}",
@@ -609,7 +614,7 @@ fn client_handshake_rejects_incompatible_version() {
     let (version, error) = client_handshake(&mut stream, 0, 80, 24)
         .expect("should read Welcome response even on rejection");
 
-    assert_eq!(version, 3, "server should report its version 3");
+    assert_eq!(version, 4, "server should report its version 4");
     assert!(
         error.is_some(),
         "version 0 should be rejected with an error"
@@ -634,10 +639,10 @@ fn client_handshake_clamps_small_terminal_size() {
     // Send Hello with 0x0 terminal size — should be clamped.
     let mut stream = UnixStream::connect(&client_socket).expect("should connect to client socket");
 
-    let (version, error) = client_handshake(&mut stream, 3, 0, 0)
+    let (version, error) = client_handshake(&mut stream, 4, 0, 0)
         .expect("handshake with 0x0 should succeed (server clamps)");
 
-    assert_eq!(version, 3);
+    assert_eq!(version, 4);
     assert!(
         error.is_none(),
         "0x0 size should be accepted (clamped): {:?}",
@@ -697,9 +702,9 @@ fn no_hello_client_closed_within_five_seconds() {
     // Verify the server is still healthy — a proper client can still connect.
     let mut good_stream =
         UnixStream::connect(&client_socket).expect("should connect after no-hello client");
-    let (version, error) = client_handshake(&mut good_stream, 3, 80, 24)
+    let (version, error) = client_handshake(&mut good_stream, 4, 80, 24)
         .expect("proper handshake should still work after no-hello client");
-    assert_eq!(version, 3);
+    assert_eq!(version, 4);
     assert!(error.is_none());
 
     // API should still work.
diff --git a/tests/support/mod.rs b/tests/support/mod.rs
index 44c25188..d26a2043 100644
--- a/tests/support/mod.rs
+++ b/tests/support/mod.rs
@@ -177,6 +177,9 @@ fn decode_welcome(payload: &[u8]) -> Result<(u32, Option<String>), String> {
     let (version, consumed) = decode_varint_u32(payload, offset)?;
     offset += consumed;
 
+    let (_encoding, consumed) = decode_varint_u32(payload, offset)?;
+    offset += consumed;
+
     if offset >= payload.len() {
         return Err("payload too short for Option tag".into());
     }
@@ -217,6 +220,7 @@ pub fn client_handshake(
             &encode_varint_u32(version),
             &encode_varint_u16(cols),
             &encode_varint_u16(rows),
+            &encode_varint_u32(0), // RenderEncoding::SemanticFrame
         ],
     );
     let framed = frame_message(&hello_payload);