[devswha]

Change

The herdr client read each reply by decoding every incoming chunk into a growing string with no limit. It cast the parsed line to a reply without checking it, and accepted the first line as the answer whatever its id. A peer that never sent a newline grew the server's memory until the timeout. A null reply surfaced as a socket_error. A reply carrying another request's id was returned as this request's answer.

• Byte framing with per-line ceilings. server/herdr/client.ts now splits incoming bytes on newlines and checks each line's size before it is decoded. A partial tail is kept as bytes, so a UTF-8 character split between reads stays whole. A line that crosses its ceiling fails at once, without waiting for a newline.
  • 64 MiB for pane.read and session.snapshot.
  • 16 MiB for every other reply and for each event line.
• Reply envelope. A reply must be an object whose string id is this request's, with exactly one of result (null allowed) or error (string code and message). Unknown fields pass through.
• Failure handling. Any other shape rejects only that request, once, as bad_frame through the existing RPC diagnostics. The message carries the method, the reason and the byte count, never the reply text, and the error is never reported as a connect failure. The next call opens a fresh socket as before.
• events.subscribe. The client keeps the subscribe request's id, and the acknowledgement must answer it. Later frames must be events (string event, object data); they need no id, and their unknown fields are kept. A frame with a string event is an event whatever else it carries, so an extra error: null does not turn it into an error reply. A malformed or oversized frame is reported once through onError, and the subscription closes once through onClose; before, such frames were dropped silently. Only each line is bounded; the stream has no lifetime byte total.

No HTTP/WS shape, setting, UI text or terminal byte changes.

Sizing

herdr's schema sets no finite maximum for a reply: PaneReadResult.text is an unbounded string, PaneReadParams.lines is a uint32, and a snapshot grows with every pane. The ceilings are therefore the bridge's supported response ceilings, not herdr's:

• Pane reads. The largest ANSI pane fixture (server/fixtures/opencode-autocomplete-2.0.32-ansi-third-selected.ansi, 40 rows) is 10,466 bytes, or 12,742 once JSON-escaped (about 319 bytes a row). The bridge's largest fixed read is 400 recent rows (server/codex.ts), about 128 KB at that rate.
• Snapshots. The test builds a schema-complete snapshot (version, protocol, focus ids, and every field of workspaces, tabs, layouts, panes and agents) for 25 workspaces, 200 tabs and 2,000 panes. It is 3,598,115 bytes of JSON. Its whole reply line, before any padding, is under 3,598,200 bytes, about 1,800 bytes a pane. Twice that is under 8 MiB.

Twice each of those is far below the 64 MiB and 16 MiB floors, so the floors stand. The test answers pane.read and session.snapshot at exactly 64 MiB, the largest supported size; the snapshot is the schema-complete one above, padded through one extension field.

Validation

• bun test ./server/herdr/seam.test.ts: 10 pass. Before the fix, the added error: null event case failed with bad_frame (reply to another request, 154 bytes); with the fix it passes. It runs against a real Unix-socket fake peer that collects complete request lines and writes chosen bytes:
  • Valid replies. A matching result keeps its unknown fields, and a null result is accepted. pane.read and session.snapshot replies at exactly 64 MiB (ANSI, escaped and multibyte text) succeed. The same size fails for any other method.
  • Malformed replies. null, arrays, strings, both or neither arms, a malformed error, and unparseable text all fail as bad_frame. So do another request's id, a numeric id and a missing id. Two lines in one read are handled in order.
  • Line ceilings. An ordinary reply at exactly 16 MiB succeeds. One byte more, with no newline, fails within milliseconds instead of at the timeout. Exact cap, cap+1, frames split byte by byte, several frames in one read, a split UTF-8 character and CRLF all decode exactly.
  • Subscriptions. An event carrying an extra error: null arrives unchanged. 2,100 events of about 8 KiB each (more than 16 MiB in total) arrive on one subscription. Wrong, unexpected and early acknowledgements, malformed events, a second acknowledgement and an oversized event line each give one onError and one onClose. herdr's own error on subscribe is still reported as herdr's.
  • Cleanup and recovery. After a protocol failure, every timer the call set is cleared and the pending count is back to 0. The peer observes the client's close, awaited with a bounded timeout. Diagnostics carry neither the reply text nor the socket path. The next RPC and the next subscription open fresh sockets and recover. Each test removes its socket directory.
• bun test ./server/rpc-diagnostics.test.ts: 5 pass.
• CHECK_WAIT_SECONDS=3600 bun run check run bun test --timeout 15000 ./server/api.contract.test.ts: 138 pass, 1 fail against an isolated herdr. The failure is the file-search assertion at server/api.contract.test.ts:1375 (/api/pane/files answers no files), which fails the same way on untouched main and is outside this change.
• CHECK_WAIT_SECONDS=3600 bun run check run bun test --timeout 15000 ./server/herdr/client.test.ts ./server/collector.contract.test.ts: 14 pass. Real herdr acknowledgements and events satisfy the stricter subscription checks.
• bun run typecheck: exit 0. bun test on the four *conventions.test.ts files: exit 0, 40 pass. bun test ./server/herdr/client.test.ts (next to the changed client, isolated herdr session): exit 0, 9 pass. The full fast check, integration and browser lanes are this PR's CI.

Ready for maintainer review; do not merge.

---

Plan todo 35 of the AoE borrowings plan. Independent verification confirmed it, two independent visual reviews passed where the change is visible, and a full CI run on this branch passed before this PR was opened: https://github.com/devswha/herdr-web-ui/actions/runs/39694006279

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: devswha/herdr-web-ui/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 4ff1aebb-0e6b-4c43-91ae-9200aac91e8a

📥 Commits

Reviewing files that changed from the base of the PR and between 586a3b8 and a62badd.

📒 Files selected for processing: 3

• changelog.d/herdr-reply-framing.md
• server/herdr/client.ts
• server/herdr/seam.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 0 remain after this review.

📝 Summary

Summary by CodeRabbit

• Bug Fixes
  • Malformed, oversized, or incorrectly addressed responses now fail the affected request with a clear error instead of hanging until timeout, using excess server memory, or being mistaken for another request’s response.
  • Event subscriptions now report malformed or oversized messages and close the subscription, rather than continuing with invalid data.

The herdr client now bounds newline-delimited frames and validates RPC replies and subscription frames. Invalid or oversized frames produce protocol errors and close affected subscriptions. Expanded seam tests cover framing limits, reply IDs and envelopes, event delivery, and connection recovery.

Changes: Herdr protocol handling

Layer / File(s)	Summary
Bounded framing and RPC reply validation server/herdr/client.ts, server/herdr/seam.test.ts, changelog.d/herdr-reply-framing.md	The client reads frames within byte limits and validates RPC reply IDs and envelopes. Malformed, mismatched, or oversized replies fail with bad_frame. Tests cover legacy error IDs, UTF-8 and split frames, large replies, and connection recovery. The changelog describes the reply-handling changes.
Subscription acknowledgement and event handling server/herdr/client.ts, server/herdr/seam.test.ts	The subscription request uses its allocated ID for acknowledgement validation. The client validates acknowledgements and event frames, and closes on malformed or oversized frames. Tests cover event delivery, callback exceptions, refusals, and reconnection.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Bug fix

Merge Risk: ⚪ Minimal · up to a62ba

This change bounds herdr reply and event frame sizes and validates reply correlation, so malformed or oversized frames fail their own request or subscription instead of hanging or growing memory. No actionable merge-blocking risk was identified in the reviewed files.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 58.82% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 2 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title is concise, specific, and accurately describes the main changes: bounding herdr reply frames and validating request correlation.
Description check		The description includes the required Change and Validation sections. It explains the problem, resulting behavior, size limits, failure handling, subscription behavior, and test results. It also ident…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Description check

Explanation

The description includes the required Change and Validation sections. It explains the problem, resulting behavior, size limits, failure handling, subscription behavior, and test results. It also identifies the known unrelated contract-test failure.

Full details: Docstring Coverage

Explanation

Docstring coverage is 58.82% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 2 files. (1 skipped: 1 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.}