Fix VZ guest exec buffering

backlog/tasks/task-12141 - Fix-VZ-Linux-real-smoke-exec-output-over-VSock.md

@@ -0,0 +1,61 @@
+---
+id: TASK-12141
+title: Fix VZ Linux real smoke exec output over VSock
+status: Done
+assignee: []
+created_date: ''
+updated_date: '2026-08-27 02:02'
+labels:
+  - sandbox
+  - vz-linux
+  - real-smoke
+  - bugfix
+dependencies: []
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Real Apple Virtualization.framework smoke reaches guest readiness but exec output propagation is unreliable: direct helper exec can time out and the host smoke can complete with empty stdout. Investigate and fix the guest/helper VSock request-response path with minimal code and tests.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Guest VSock client preserves host bytes buffered immediately after ready ACK
+- [x] #2 Regression test covers ready ACK plus exec request in one host write
+- [x] #3 Real host VZ smoke passes with rebuilt guest bundle
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+<!-- SECTION:IMPLEMENTATION_NOTES:BEGIN -->
+['Observed on local Apple Silicon host with signed macos-vz-helper and Debian arm64 bundle.', 'Helper daemon bundle smoke passed. Real smoke selected tests: 2 passed, 1 failed on missing stdout token.', 'Manual helper probe reached guest readiness then direct exec_guest timed out at guest_transport_timeout.', 'Leading hypothesis: guest VSock client primes handshake/ready with bufio.Reader, then ServeStream reads from raw conn; bytes buffered after ready can be lost from ServeStream.']
+<!-- SECTION:IMPLEMENTATION_NOTES:END -->
+
+Root cause confirmed with failing test: primeConnection used a bufio.Reader for handshake/ready, then Run passed the raw conn into ServeStream. If the helper's ready ACK and first exec request arrived together, the exec bytes could remain buffered in the discarded reader.
+
+Fix: return the priming bufio.Reader from primeConnection and pass it to ServeStream so buffered exec bytes remain visible.
+
+Verification: GOCACHE=/private/tmp/tldw-go-build-cache go test ./internal/guest; GOCACHE=/private/tmp/tldw-go-build-cache go test ./... in tools/tldw-agent; rebuilt Debian arm64 bundle; real host smoke final_exit_code=0 at /private/tmp/tvz-e2e.4iJ3wt/evidence/host-smoke-evidence.json.
+
+Bandit: not applicable to touched production code; this change is Go-only under tools/tldw-agent.
+
+PR review follow-up: updated TestGuestVSockClientRunPreservesExecBufferedAfterReady to wait for and validate the exec response before closing the helper-side pipe, removing the race noted in review.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Fixed VZ Linux guest VSock exec delivery by preserving the buffered reader used during handshake/readiness when entering ServeStream. Added a regression test for ready ACK plus exec request arriving in one host write, then verified unit tests and real Apple VZ smoke against a rebuilt Debian arm64 bundle.
+<!-- SECTION:FINAL_SUMMARY:END -->
+
+## Definition of Done
+<!-- DOD:BEGIN -->
+- [x] #1 Acceptance criteria completed
+- [x] #2 Tests or verification recorded
+- [x] #3 Documentation updated when relevant
+- [x] #4 Bandit run for touched code when applicable or document non-code/environment skip
+- [x] #5 Final summary added
+- [x] #6 Known skips or blockers documented
+<!-- DOD:END -->

tools/tldw-agent/internal/guest/vsock_client.go

@@ -68,13 +68,13 @@ func (c *VSockClient) Run(ctx context.Context, server *Server) error {
 			return err
 		}
 
-		err = c.primeConnection(ctx, conn, server, reconnect)
+		reader, err := c.primeConnection(ctx, conn, server, reconnect)
 		if err != nil {
 			_ = conn.Close()
 			return err
 		}
 
-		err = server.ServeStream(conn, conn)
+		err = server.ServeStream(reader, conn)
 		_ = conn.Close()
 		if err != nil {
 			return err
@@ -97,24 +97,24 @@ func (c *VSockClient) primeConnection(
 	conn io.ReadWriteCloser,
 	server *Server,
 	reconnect bool,
-) error {
+) (*bufio.Reader, error) {
 	reader := bufio.NewReader(conn)
 	if reconnect {
 		if err := c.sendReconnect(conn, reader); err != nil {
-			return err
+			return nil, err
 		}
 	} else {
 		if err := c.sendHandshake(conn, reader); err != nil {
-			return err
+			return nil, err
 		}
 	}
 	if err := c.sendReady(conn, reader, server); err != nil {
-		return err
+		return nil, err
 	}
 	if ctx.Err() != nil {
-		return ctx.Err()
+		return nil, ctx.Err()
 	}
-	return nil
+	return reader, nil
 }
 
 func (c *VSockClient) sendHandshake(conn io.Writer, reader *bufio.Reader) error {

tools/tldw-agent/internal/guest/vsock_client_test.go

@@ -3,10 +3,12 @@ package guest
 import (
 	"bufio"
 	"context"
+	"encoding/json"
 	"io"
 	"net"
 	"reflect"
 	"testing"
+	"time"
 )
 
 type recordingDialer struct {
@@ -104,7 +106,7 @@ func TestGuestVSockClientSendsHandshakeAndReady(t *testing.T) {
 		done <- nil
 	}()
 
-	if err := client.primeConnection(context.Background(), guestConn, server, false); err != nil {
+	if _, err := client.primeConnection(context.Background(), guestConn, server, false); err != nil {
 		t.Fatalf("primeConnection() error = %v", err)
 	}
 	if err := <-done; err != nil {
@@ -204,21 +206,116 @@ func TestGuestVSockClientReconnectsWithSameVMIDAndToken(t *testing.T) {
 	go assertHello(firstHelperConn, "handshake", firstDone)
 	go assertHello(secondHelperConn, "reconnect", secondDone)
 
-	if err := client.primeConnection(context.Background(), firstGuestConn, server, false); err != nil {
+	if _, err := client.primeConnection(context.Background(), firstGuestConn, server, false); err != nil {
 		t.Fatalf("primeConnection(first) error = %v", err)
 	}
 	if err := <-firstDone; err != nil {
 		t.Fatalf("first helper side error = %v", err)
 	}
 
-	if err := client.primeConnection(context.Background(), secondGuestConn, server, true); err != nil {
+	if _, err := client.primeConnection(context.Background(), secondGuestConn, server, true); err != nil {
 		t.Fatalf("primeConnection(second) error = %v", err)
 	}
 	if err := <-secondDone; err != nil {
 		t.Fatalf("second helper side error = %v", err)
 	}
 }
 
+func TestGuestVSockClientRunPreservesExecBufferedAfterReady(t *testing.T) {
+	root := t.TempDir()
+	server, err := NewServer(root)
+	if err != nil {
+		t.Fatalf("NewServer() error = %v", err)
+	}
+
+	guestConn, helperConn := net.Pipe()
+	client := &VSockClient{
+		cfg: VSockClientConfig{
+			VMID:            "vm-buffered-exec",
+			ConnectionToken: "token-buffered-exec",
+			HostPort:        4242,
+			WorkspaceRoot:   root,
+			GuestVersion:    "1.0.0",
+		},
+		dialer: &recordingDialer{conns: []io.ReadWriteCloser{guestConn}},
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	helperDone := make(chan error, 1)
+	go func() {
+		defer helperConn.Close()
+		reader := bufio.NewReader(helperConn)
+
+		var handshake HandshakeRequest
+		if err := decodeLine(reader, &handshake); err != nil {
+			helperDone <- err
+			return
+		}
+		if err := writeJSONLine(helperConn, HandshakeAck{
+			ProtocolVersion: ProtocolVersion,
+			RequestID:       handshake.RequestID,
+			Type:            "handshake_ack",
+			Status:          "accepted",
+			VMID:            handshake.VMID,
+		}); err != nil {
+			helperDone <- err
+			return
+		}
+
+		var ready ReadyRequest
+		if err := decodeLine(reader, &ready); err != nil {
+			helperDone <- err
+			return
+		}
+		readyPayload, err := json.Marshal(ReadyResponse{
+			ProtocolVersion: ProtocolVersion,
+			RequestID:       ready.RequestID,
+			Status:          "ready",
+			WorkspaceRoot:   root,
+		})
+		if err != nil {
+			helperDone <- err
+			return
+		}
+
+		execPayload := []byte(`{"protocol_version":"1","request_id":"req-buffered-exec","type":"exec","argv":["/bin/echo","preserved"],"cwd":"."}`)
+		payload := append(append(readyPayload, '\n'), execPayload...)
+		payload = append(payload, '\n')
+		if _, err = helperConn.Write(payload); err != nil {
+			helperDone <- err
+			return
+		}
+
+		if err = helperConn.SetReadDeadline(time.Now().Add(time.Second)); err != nil {
+			helperDone <- err
+			return
+		}
+		var execResp ExecResponse
+		if err = decodeLine(reader, &execResp); err != nil {
+			helperDone <- err
+			return
+		}
+		if execResp.RequestID != "req-buffered-exec" {
+			helperDone <- errUnexpectedValue("exec request id", execResp.RequestID)
+			return
+		}
+		if execResp.Stdout != "preserved\n" {
+			helperDone <- errUnexpectedValue("exec stdout", execResp.Stdout)
+			return
+		}
+		cancel()
+		helperDone <- nil
+	}()
+
+	if err := client.Run(ctx, server); err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	if err := <-helperDone; err != nil {
+		t.Fatalf("helper side error = %v", err)
+	}
+}
+
 type unexpectedValueError struct {
 	name  string
 	value any