Fix VZ guest exec buffering

[rmusser01]

Summary

• Fixes VZ Linux guest exec delivery by preserving the buffered reader used during VSock handshake/readiness when entering command serving.
• Adds and hardens a regression test for the ready ACK and first exec request arriving in the same host write.
• Records the work in Backlog task TASK-13134.

Verification

• GOCACHE=/private/tmp/tldw-go-build-cache go test ./internal/guest
• GOCACHE=/private/tmp/tldw-go-build-cache go test ./...
• git diff --check
• Real local Apple VZ smoke with rebuilt Debian arm64 bundle:
  • helper daemon bundle smoke: 2 passed
  • real host smoke: 3 passed
  • evidence: /private/tmp/tvz-e2e.4iJ3wt/evidence/host-smoke-evidence.json
  • final_exit_code: 0

Change Summary

This PR fixes the real VZ Linux exec path by preserving the buffered VSock reader after guest handshake/readiness, preventing the first exec request from being lost when it arrives immediately after the ready response. It adds a regression test for that exact buffering edge case and verifies the fix with the Go agent test suite plus a real local Apple VZ smoke run using a rebuilt Debian arm64 bundle.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 58ca08f5-6329-4f60-b6fa-d4e781095151

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/vz-real-smoke-debug

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[gemini-code-assist]

Code Review

This pull request fixes a bug where VSock execution output was unreliable due to buffered bytes being lost. By returning the bufio.Reader used during the handshake in primeConnection and passing it to ServeStream, any bytes buffered immediately after the ready ACK are preserved. A regression test was also added to verify this behavior. The review feedback correctly identifies a potential race condition in this new test, where the helper goroutine closes the connection immediately after writing the payload, and suggests waiting for the client's response to ensure test robustness.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[qodo-code-review]

PR Summary by Qodo

Preserve buffered VSock exec requests after guest readiness

🐞 Bug fix 🧪 Tests 📝 Documentation 🕐 10-20 Minutes

AI Description

• Preserves VSock handshake buffering when command serving begins, preventing dropped initial exec
 requests.
• Adds deterministic regression coverage for coalesced ready ACK and exec request delivery.
• Records root cause, acceptance criteria, and real Apple VZ smoke verification in TASK-12141.

Diagram

sequenceDiagram
    participant H as Host Helper
    participant C as VSock Client
    participant R as Buffered Reader
    participant S as Guest Server
    C->>H: Handshake and ready
    H-->>R: Ready ACK plus exec
    R-->>C: Ready ACK
    C->>S: ServeStream reader
    R-->>S: Buffered exec request
    S->>S: Execute command
    S-->>H: Exec response

Loading

High-Level Assessment

Retaining and passing the existing buffered reader is the minimal and correct fix because it preserves bytes already consumed from the socket without changing the protocol or command server. Reconstructing the reader or manually draining buffered bytes would add state-transfer complexity and greater risk.

Files changed (3) +169 / -11

Bug fix (1) +8 / -8

vsock_client.goReuse the priming reader for VSock command serving +8/-8

Reuse the priming reader for VSock command serving

• Changes connection priming to return its bufio.Reader and passes that reader into ServeStream. This prevents bytes read ahead after the ready acknowledgment from being discarded before the first exec request is handled.

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

Tests (1) +100 / -3

vsock_client_test.goCover exec requests buffered with the ready acknowledgment +100/-3

Cover exec requests buffered with the ready acknowledgment

• Updates existing tests for the new primeConnection return value and adds a net.Pipe regression test that sends the ready response and first exec request in one write. The test waits for and validates the exec response, avoiding closure-based race behavior.

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

Documentation (1) +61 / -0

task-12141 - Fix-VZ-Linux-real-smoke-exec-output-over-VSock.mdDocument the VZ VSock buffering fix and verification +61/-0

Document the VZ VSock buffering fix and verification

• Adds completed task TASK-12141 with the observed failure, confirmed buffering root cause, acceptance criteria, implementation notes, and unit plus real Apple VZ smoke evidence.

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

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. One-second deadline risks flakiness ✓ Resolved 📘 Rule violation ▣ Testability

Description

The regression test gives the full buffered request handling and /bin/echo execution only one
second before failing. Under a loaded CI runner, this wall-clock deadline can expire despite correct
behavior, making the test non-deterministic.

Code

tools/tldw-agent/internal/guest/vsock_client_test.go[290]

+		if err = helperConn.SetReadDeadline(time.Now().Add(time.Second)); err != nil {

Evidence

Rules 224239 and 380653 require changed tests to avoid timing-dependent failures and permit timeouts
only when they are sufficiently stable for CI. The added line derives a network deadline directly
from the wall clock and allows only one second for request processing, process execution, and
response delivery.

Rule 224239: Tests must be deterministic and isolated from external state
Rule 380653: Tests must be deterministic and avoid non-deterministic sources
tools/tldw-agent/internal/guest/vsock_client_test.go[290-290]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The regression test uses a one-second wall-clock read deadline, which can fail on slow or heavily loaded CI runners even when the buffered exec path works correctly.

## Issue Context
Keep the wait bounded so genuine hangs still fail, but use a substantially more tolerant test timeout or the repository's standard timeout helper.

## Fix Focus Areas
- tools/tldw-agent/internal/guest/vsock_client_test.go[290-290]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

✅ Compliance rules (platform): 74 rules

Review mode: ⚖️ Balanced: This is a runtime VSock protocol fix affecting guest command delivery, with buffering and asynchronous handshake/exec behavior requiring a careful complete review.

Tip of the day

💡 Did you know, you can ask Qodo to dismiss a finding you disagree with, with your reason on record

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗