Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

fix(backend): raise terminal relay budget to 64 busy streams per socket (#1367)

0xken15d1fcaa16d0e5
diff --git a/backend/src/lib/terminalRelay.test.ts b/backend/src/lib/terminalRelay.test.ts
index 1097f317a..03349ff79 100644
--- a/backend/src/lib/terminalRelay.test.ts
+++ b/backend/src/lib/terminalRelay.test.ts
@@ -77,6 +77,11 @@ describe('terminal opaque relay contract', () => {
expect(guard.allow('terminal_ack', 120)).toBe(true)
})
+ it('sizes the relay for 64 busy harnesses on one machine', () => {
+ // A person driving many harnesses on one remote machine hit the 16-stream budget (2026-10-16).
+ expect(RELAY_BUSY_STREAMS).toBe(64)
+ })
+
it('lets RELAY_BUSY_STREAMS renderers ack on one socket for a whole minute', () => {
let now = 1_000
const guard = new TerminalRateGuard(() => now)
@@ -96,15 +101,16 @@ describe('terminal opaque relay contract', () => {
const guard = new TerminalRateGuard(() => 1_000)
const frames = RELAY_BUSY_STREAMS * (60_000 / 8)
let allowed = 0
- for (let i = 0; i < frames; i++) if (guard.allow('terminal_output', 256)) allowed++
+ // ~1 KiB is a typical compressed, sealed output frame; the byte cap must not bind before the frame cap.
+ for (let i = 0; i < frames; i++) if (guard.allow('terminal_output', 1_024)) allowed++
expect(allowed).toBe(frames)
- expect(guard.allow('terminal_output', 256)).toBe(false)
+ expect(guard.allow('terminal_output', 1_024)).toBe(false)
})
it('keeps a worst-case encrypted ack small enough for the ack byte budget', () => {
// Pins the size the ack budget was derived from (216 B). A frame that grows past
- // 16 MiB / 60,000 = 279 B would make the byte cap trip before the frame cap.
- expect(terminalFrameBytes(worstCaseAck())).toBeLessThanOrEqual(Math.floor((16 * 1024 * 1024) / 60_000))
+ // 64 MiB / 240,000 = 279 B would make the byte cap trip before the frame cap.
+ expect(terminalFrameBytes(worstCaseAck())).toBeLessThanOrEqual(Math.floor((64 * 1024 * 1024) / 240_000))
})
it('wakes only for terminal_open, never per input/mouse/resize/ack frame', () => {
diff --git a/backend/src/lib/terminalRelay.ts b/backend/src/lib/terminalRelay.ts
index ad8e4ec9c..e6e193da4 100644
--- a/backend/src/lib/terminalRelay.ts
+++ b/backend/src/lib/terminalRelay.ts
@@ -41,9 +41,12 @@ export function isEncryptedTerminalFrame(frame: Frame): boolean {
* E2EE and the stream id is inside the ciphertext. The ack and output buckets were once sized for a
* single busy stream, and three panes of one machine streaming over the relay tripped them. A rejected
* ack answers TERMINAL_FRAME_REJECTED, which every pane on the socket reads as transport loss and shows
- * as Reconnect (2026-10-16). They are now sized for this many busy streams per socket.
+ * as Reconnect (2026-10-16). They are now sized for this many busy streams per socket: 16 was still
+ * reachable by one person driving many harnesses on one machine, so it was raised the same day. Each
+ * frame costs a parse and a Redis publish, so cutting frames at the source (fewer acks, coarser relay
+ * flushes) is the way past this, not another raise.
*/
-export const RELAY_BUSY_STREAMS = 16
+export const RELAY_BUSY_STREAMS = 64
/** A renderer acks once per 16 ms render window, plus once per 64 KiB rendered, while output flows. */
const ACKS_PER_STREAM_PER_MINUTE = 3_750
/** The daemon flushes a remote stream's output at most every 8 ms (`OUTPUT_FLUSH_MS` in the CLI). */
@@ -57,18 +60,19 @@ interface Bucket {
function limits(type: string): { frames: number; bytes: number } {
if (type === 'terminal_input') return { frames: 15_000, bytes: 64 * 1024 * 1024 }
- // Bytes, not frames, bound the volume; the frame count only has to clear legitimate flush cadence.
+ // The byte cap scales with the frame cap at ~1 KiB per frame (a typical compressed, sealed flush),
+ // so neither binds first for legitimate traffic: 8 MiB per busy stream per minute.
if (type === 'terminal_output') {
- return { frames: RELAY_BUSY_STREAMS * OUTPUT_FRAMES_PER_STREAM_PER_MINUTE, bytes: 128 * 1024 * 1024 }
+ return { frames: RELAY_BUSY_STREAMS * OUTPUT_FRAMES_PER_STREAM_PER_MINUTE, bytes: RELAY_BUSY_STREAMS * 8 * 1024 * 1024 }
}
if (type === 'terminal_sync') return { frames: 1_200, bytes: 8 * 1024 * 1024 }
// Acks are renderer flow control, not user actions, and cannot be dropped quietly: the host pauses
// output at 384 KiB unacknowledged and closes the stream (TERMINAL_RENDER_STALLED) if the ack that
// would resume it never arrives. Sharing the human-paced 1,200 below once let a single pane
// streaming a build log exhaust the window in about 19 seconds. A worst-case encrypted ack is
- // 216 B (pinned in terminalRelay.test.ts), so 60,000 of them fit in 16 MiB.
+ // 216 B (pinned in terminalRelay.test.ts), so 1 MiB per busy stream per minute holds its 3,750.
if (type === 'terminal_ack') {
- return { frames: RELAY_BUSY_STREAMS * ACKS_PER_STREAM_PER_MINUTE, bytes: 16 * 1024 * 1024 }
+ return { frames: RELAY_BUSY_STREAMS * ACKS_PER_STREAM_PER_MINUTE, bytes: RELAY_BUSY_STREAMS * 1024 * 1024 }
}
if (type === 'terminal_alive' || type === 'terminal_resize' || type === 'terminal_scroll') {
return { frames: 1_200, bytes: 8 * 1024 * 1024 }
diff --git a/docs/plans/2026-10-16-terminal-relay-rate-budget.md b/docs/plans/2026-10-16-terminal-relay-rate-budget.md
index d309e233d..f17b5409b 100644
--- a/docs/plans/2026-10-16-terminal-relay-rate-budget.md
+++ b/docs/plans/2026-10-16-terminal-relay-rate-budget.md
@@ -117,3 +117,12 @@ says it matters.
come.
- Phase 3: `TerminalSession` failure reasons go to `debugPrint` only, not to
`~/.harness/logs/app-*.log`.
+
+## Update, same day: 64 busy streams
+
+16 was still reachable by one person driving many harnesses on one remote machine, so
+`RELAY_BUSY_STREAMS` became 64 as a stopgap, with byte caps that scale with it so neither cap binds
+first: acks 240,000 frames / 64 MiB per minute (1 MiB per stream), output 480,000 frames / 512 MiB
+per minute (8 MiB per stream, ~1 KiB per frame). Each frame costs the backend a parse and a Redis
+publish, so the durable fix is fewer frames at the source (client ack cadence, coarser relay
+flushes in the daemon), not further raises. Watch pod CPU after this deploy.