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): size terminal relay ack/output budgets per socket, not per stream (#1365)

0xken1548cd362e9a9c
diff --git a/backend/src/lib/terminalRelay.test.ts b/backend/src/lib/terminalRelay.test.ts
index c35c559cc..1097f317a 100644
--- a/backend/src/lib/terminalRelay.test.ts
+++ b/backend/src/lib/terminalRelay.test.ts
@@ -1,6 +1,8 @@
import { describe, expect, it } from 'vitest'
+import type { Frame } from './tunnel.js'
import {
isEncryptedTerminalFrame,
+ RELAY_BUSY_STREAMS,
TERMINAL_DOWN_TYPES,
TERMINAL_UP_TYPES,
terminalFrameBytes,
@@ -8,6 +10,17 @@ import {
TerminalRateGuard,
} from './terminalRelay.js'
+/** The largest `terminal_ack` a client can send, shaped exactly as the relay wraps it: the plaintext
+ * payload sealed with a 16-byte AEAD tag, base64'd into an `__e2e` envelope. */
+function worstCaseAck(): Frame {
+ const plaintext = JSON.stringify({
+ streamId: '00000000-0000-4000-8000-000000000000',
+ lastSeq: Number.MAX_SAFE_INTEGER,
+ })
+ const ct = Buffer.alloc(Buffer.byteLength(plaintext) + 16).toString('base64')
+ return { type: 'terminal_ack', payload: { __e2e: { v: 1, k: 'p', n: Number.MAX_SAFE_INTEGER, ct } } }
+}
+
describe('terminal opaque relay contract', () => {
it('keeps the expected direction allowlists disjoint', () => {
expect([...TERMINAL_DOWN_TYPES].sort()).toEqual([
@@ -64,6 +77,36 @@ describe('terminal opaque relay contract', () => {
expect(guard.allow('terminal_ack', 120)).toBe(true)
})
+ it('lets RELAY_BUSY_STREAMS renderers ack on one socket for a whole minute', () => {
+ let now = 1_000
+ const guard = new TerminalRateGuard(() => now)
+ // One guard serves the socket, and every pane of the machine shares it. Each busy pane acks once
+ // per 16 ms render window; the worst-case frame size makes the byte cap part of the check.
+ const acks = RELAY_BUSY_STREAMS * Math.ceil(60_000 / 16)
+ const bytes = terminalFrameBytes(worstCaseAck())
+ let allowed = 0
+ for (let i = 0; i < acks; i++) if (guard.allow('terminal_ack', bytes)) allowed++
+ expect(allowed).toBe(acks)
+ expect(guard.allow('terminal_ack', bytes)).toBe(false)
+ now += 60_000
+ expect(guard.allow('terminal_ack', bytes)).toBe(true)
+ })
+
+ it('lets RELAY_BUSY_STREAMS streams flush output every 8 ms through one adapter for a whole minute', () => {
+ 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++
+ expect(allowed).toBe(frames)
+ expect(guard.allow('terminal_output', 256)).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))
+ })
+
it('wakes only for terminal_open, never per input/mouse/resize/ack frame', () => {
expect(terminalFrameNeedsWake('terminal_open')).toBe(true)
for (const type of TERMINAL_DOWN_TYPES) {
diff --git a/backend/src/lib/terminalRelay.ts b/backend/src/lib/terminalRelay.ts
index 38e92ad3a..ad8e4ec9c 100644
--- a/backend/src/lib/terminalRelay.ts
+++ b/backend/src/lib/terminalRelay.ts
@@ -35,6 +35,20 @@ export function isEncryptedTerminalFrame(frame: Frame): boolean {
&& typeof value.ct === 'string'
}
+/**
+ * One TerminalRateGuard serves a whole socket (a web client's connection, or a machine's adapter), so
+ * every stream on it shares each bucket below. The backend cannot split them: terminal frames are
+ * 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.
+ */
+export const RELAY_BUSY_STREAMS = 16
+/** 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). */
+const OUTPUT_FRAMES_PER_STREAM_PER_MINUTE = 7_500
+
interface Bucket {
startedAt: number
frames: number
@@ -43,15 +57,19 @@ interface Bucket {
function limits(type: string): { frames: number; bytes: number } {
if (type === 'terminal_input') return { frames: 15_000, bytes: 64 * 1024 * 1024 }
- if (type === 'terminal_output') return { frames: 20_000, bytes: 128 * 1024 * 1024 }
+ // Bytes, not frames, bound the volume; the frame count only has to clear legitimate flush cadence.
+ if (type === 'terminal_output') {
+ return { frames: RELAY_BUSY_STREAMS * OUTPUT_FRAMES_PER_STREAM_PER_MINUTE, bytes: 128 * 1024 * 1024 }
+ }
if (type === 'terminal_sync') return { frames: 1_200, bytes: 8 * 1024 * 1024 }
- // Acks are renderer flow control, not user actions. The client emits one per 16ms render window
- // (plus one per 64 KiB rendered), so roughly 3,750/min while output is flowing. Sharing the
- // human-paced 1,200 below meant a pane streaming a build log exhausted the window in about 19
- // seconds, and a rejected ack is not dropped quietly — it answers TERMINAL_FRAME_REJECTED, which
- // the client reads as transport loss and freezes the pane mid-output. Sized ~2.7x the client's
- // own ceiling; the byte cap still bounds actual volume.
- if (type === 'terminal_ack') return { frames: 10_000, 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.
+ if (type === 'terminal_ack') {
+ return { frames: RELAY_BUSY_STREAMS * ACKS_PER_STREAM_PER_MINUTE, bytes: 16 * 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-implementation.md b/docs/plans/2026-10-16-terminal-relay-rate-budget-implementation.md
new file mode 100644
index 000000000..9f1d41814
--- /dev/null
+++ b/docs/plans/2026-10-16-terminal-relay-rate-budget-implementation.md
@@ -0,0 +1,189 @@
+# Terminal Relay Rate Budget Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Stop the backend's per-socket terminal rate guard from rejecting legitimate traffic when several panes of one machine stream over the ws relay.
+
+**Architecture:** One `TerminalRateGuard` serves a whole socket, but its `terminal_ack` and `terminal_output` limits were sized for one stream. Size them for `RELAY_BUSY_STREAMS = 16` busy streams per socket by multiplying the per-stream rates. Change only `limits()` in `backend/src/lib/terminalRelay.ts`; rejection semantics stay as they are.
+
+**Tech Stack:** TypeScript, Node, vitest (backend).
+
+**Spec:** `docs/plans/2026-10-16-terminal-relay-rate-budget.md`
+
+## Global Constraints
+
+- Backend only: no change under `cli/`, `desktop/`, `mobile/`, or `desktop/lib/web/`.
+- `RELAY_BUSY_STREAMS = 16`.
+- `terminal_ack`: 16 × 3,750 = **60,000 frames/min**, bytes **16 MiB**.
+- `terminal_output`: 16 × 7,500 = **120,000 frames/min**, bytes stay **128 MiB**.
+- Every other bucket is unchanged.
+- Rejection semantics are unchanged. Down rejections still answer `TERMINAL_FRAME_REJECTED`; up rejections still drop silently.
+- Do not commit. Leave the change in the working tree; the owner commits.
+- Repo docs and comments in English. Comments say why, and name the incident or measurement.
+
+## Review Focus
+
+1. **Byte cap binding before frame cap for acks.** A worst-case encrypted ack (`lastSeq` = `Number.MAX_SAFE_INTEGER`, `n` = `Number.MAX_SAFE_INTEGER`) is 216 B. 60,000 of them must fit in 16 MiB. Task 1's ack test runs at that exact size.
+2. **The 60,001st ack / 120,001st output frame is still refused.** The guard must not become unlimited. Task 1's tests assert the next frame fails.
+3. **Window reset still works at the new sizes.** After 60 s the bucket refills. The existing test covers `terminal_open`, and Task 1 adds the same check for `terminal_ack`.
+4. **Other buckets did not move.** The existing test "lets a busy renderer ack…" still asserts `terminal_alive` trips at 1,200; keep it passing unchanged.
+5. **Legacy key path and web path share `limits()`.** `webWs.ts:131` and `:589` both construct `TerminalRateGuard`, so no change is needed there. `webWs.test.ts` must still pass.
+
+---
+
+### Task 1: Size the ack and output buckets for 16 busy streams per socket
+
+**Files:**
+- Modify: `backend/src/lib/terminalRelay.ts` (the `limits()` function and the comment above `terminal_ack`, lines ~44–63)
+- Test: `backend/src/lib/terminalRelay.test.ts`
+
+**Interfaces:**
+- Consumes: `TerminalRateGuard`, `terminalFrameBytes` (existing exports of `terminalRelay.ts`); `Frame` type from `backend/src/lib/tunnel.ts` (`Record<string, unknown>`).
+- Produces: `export const RELAY_BUSY_STREAMS = 16` in `terminalRelay.ts`.
+
+- [ ] **Step 1: Write the failing tests**
+
+In `backend/src/lib/terminalRelay.test.ts`, extend the import and add a helper plus three tests inside the existing `describe('terminal opaque relay contract', …)` block, right after the test "lets a busy renderer ack for a whole window without losing its stream":
+
+```ts
+import { describe, expect, it } from 'vitest'
+import type { Frame } from './tunnel.js'
+import {
+ isEncryptedTerminalFrame,
+ RELAY_BUSY_STREAMS,
+ TERMINAL_DOWN_TYPES,
+ TERMINAL_UP_TYPES,
+ terminalFrameBytes,
+ terminalFrameNeedsWake,
+ TerminalRateGuard,
+} from './terminalRelay.js'
+
+/** The largest `terminal_ack` a client can send, shaped exactly as the relay wraps it: the plaintext
+ * payload sealed with a 16-byte AEAD tag, base64'd into an `__e2e` envelope. */
+function worstCaseAck(): Frame {
+ const plaintext = JSON.stringify({
+ streamId: '00000000-0000-4000-8000-000000000000',
+ lastSeq: Number.MAX_SAFE_INTEGER,
+ })
+ const ct = Buffer.alloc(Buffer.byteLength(plaintext) + 16).toString('base64')
+ return { type: 'terminal_ack', payload: { __e2e: { v: 1, k: 'p', n: Number.MAX_SAFE_INTEGER, ct } } }
+}
+```
+
+```ts
+ it('lets RELAY_BUSY_STREAMS renderers ack on one socket for a whole minute', () => {
+ let now = 1_000
+ const guard = new TerminalRateGuard(() => now)
+ // One guard serves the socket, and every pane of the machine shares it. Each busy pane acks once
+ // per 16 ms render window; the worst-case frame size makes the byte cap part of the check.
+ const acks = RELAY_BUSY_STREAMS * Math.ceil(60_000 / 16)
+ const bytes = terminalFrameBytes(worstCaseAck())
+ let allowed = 0
+ for (let i = 0; i < acks; i++) if (guard.allow('terminal_ack', bytes)) allowed++
+ expect(allowed).toBe(acks)
+ expect(guard.allow('terminal_ack', bytes)).toBe(false)
+ now += 60_000
+ expect(guard.allow('terminal_ack', bytes)).toBe(true)
+ })
+
+ it('lets RELAY_BUSY_STREAMS streams flush output every 8 ms through one adapter for a whole minute', () => {
+ 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++
+ expect(allowed).toBe(frames)
+ expect(guard.allow('terminal_output', 256)).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))
+ })
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `cd backend && npm test -- src/lib/terminalRelay.test.ts`
+Expected: FAIL. `RELAY_BUSY_STREAMS` is not exported, so it is `undefined`: the ack test's `acks` is `NaN` and `expect(allowed).toBe(acks)` fails. After Step 3 adds only the constant and not the limits, it would instead fail with `expected 10000 to be 60000`.
+
+- [ ] **Step 3: Implement the limits**
+
+In `backend/src/lib/terminalRelay.ts`, add these constants directly above `interface Bucket`:
+
+```ts
+/**
+ * One TerminalRateGuard serves a whole socket (a web client's connection, or a machine's adapter), so
+ * every stream on it shares each bucket below. The backend cannot split them: terminal frames are
+ * 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.
+ */
+export const RELAY_BUSY_STREAMS = 16
+/** 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). */
+const OUTPUT_FRAMES_PER_STREAM_PER_MINUTE = 7_500
+```
+
+Then, in `limits()`, replace the `terminal_output` line:
+
+```ts
+ if (type === 'terminal_output') return { frames: 20_000, bytes: 128 * 1024 * 1024 }
+```
+
+with:
+
+```ts
+ // Bytes, not frames, bound the volume; the frame count only has to clear legitimate flush cadence.
+ if (type === 'terminal_output') {
+ return { frames: RELAY_BUSY_STREAMS * OUTPUT_FRAMES_PER_STREAM_PER_MINUTE, bytes: 128 * 1024 * 1024 }
+ }
+```
+
+and replace the ack comment and line:
+
+```ts
+ // Acks are renderer flow control, not user actions. The client emits one per 16ms render window
+ // (plus one per 64 KiB rendered), so roughly 3,750/min while output is flowing. Sharing the
+ // human-paced 1,200 below meant a pane streaming a build log exhausted the window in about 19
+ // seconds, and a rejected ack is not dropped quietly — it answers TERMINAL_FRAME_REJECTED, which
+ // the client reads as transport loss and freezes the pane mid-output. Sized ~2.7x the client's
+ // own ceiling; the byte cap still bounds actual volume.
+ if (type === 'terminal_ack') return { frames: 10_000, bytes: 8 * 1024 * 1024 }
+```
+
+with:
+
+```ts
+ // 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.
+ if (type === 'terminal_ack') {
+ return { frames: RELAY_BUSY_STREAMS * ACKS_PER_STREAM_PER_MINUTE, bytes: 16 * 1024 * 1024 }
+ }
+```
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `cd backend && npm test -- src/lib/terminalRelay.test.ts`
+Expected: PASS. All tests pass, including the unchanged "rate-limits per type in a bounded one-minute window" and "lets a busy renderer ack for a whole window without losing its stream".
+
+- [ ] **Step 5: Run the neighbouring suites and the typecheck**
+
+Run: `cd backend && npm test -- src/lib/webWs.test.ts src/lib/terminalRelay.test.ts && npm run typecheck`
+Expected: PASS and no type errors.
+
+- [ ] **Step 6: Leave uncommitted**
+
+Do not commit (owner preference). Report `git status --short` and `git diff --stat`. Expected: two files changed, `backend/src/lib/terminalRelay.ts` and `backend/src/lib/terminalRelay.test.ts`. The spec and this plan under `docs/plans/` are also untracked.
+
+---
+
+## After the task (owner's call, not part of execution)
+
+- PR with `ci/required` (backend component checks), then `make merge-pr`, then `make release-backend`.
+- Post-deploy check from the spec: put a remote machine on the ws relay (p2p off or failed) and run steady output in four panes for two minutes. No pane should show Reconnect or flap through Restoring.
diff --git a/docs/plans/2026-10-16-terminal-relay-rate-budget.md b/docs/plans/2026-10-16-terminal-relay-rate-budget.md
new file mode 100644
index 000000000..d309e233d
--- /dev/null
+++ b/docs/plans/2026-10-16-terminal-relay-rate-budget.md
@@ -0,0 +1,119 @@
+# Terminal relay rate budget: size it per socket, not per stream
+
+Requested 2026-10-16. Phase 1 of the "remote terminal keeps showing Reconnect while the network is
+fine" investigation. Scope: `backend/src/lib/terminalRelay.ts` only. No client or CLI change, no app
+release. Phases 2 (recovery after a host's backend link drops) and 3 (terminal failure reasons in the
+desktop's file log) get their own specs.
+
+## Problem
+
+`TerminalRateGuard` counts terminal frames in a one-minute window, keyed by frame type. One guard is
+created per socket — per web client connection (`webWs.ts:131`, and the legacy key path at `:589`)
+and per adapter connection (`adapterWs.ts:219`) — so every stream that socket carries shares each
+bucket. The limits in `limits()` were sized for **one** stream:
+
+| Bucket | Limit today | One busy stream emits | Streams before it trips |
+|---|---|---|---|
+| `terminal_ack` (down, web socket) | 10,000 frames, 8 MiB | 3,750/min (one ack per 16 ms render window, plus one per 64 KiB) | ~2.7 |
+| `terminal_output` (up, adapter socket) | 20,000 frames, 128 MiB | up to 7,500/min (`OUTPUT_FLUSH_MS = 8`) | ~2.7 |
+
+The comment on the ack limit ("sized ~2.7x the client's own ceiling") reads that ceiling as the
+socket's, but it is a single stream's.
+
+What a user sees when the limit trips:
+
+- **Down (ack).** Three panes of one remote machine with steady output (Codex or Claude streaming, a
+ build log) on the ws relay exceed 10,000 acks in a minute. The backend answers
+ `terminal_transport_error {code: TERMINAL_FRAME_REJECTED}`. The daemon's relay passes the
+ unwrapped frame to the app (`remoteRelay.ts`, `unwrapIncoming` returns non-E2EE frames as they
+ are). `TerminalSession` handles it with no stream filter (`terminal_session.dart:740`, same in
+ mobile), so **every** pane of that machine calls `transportLost` and shows Reconnect.
+- **Up (output).** Over budget, the adapter path drops the binary frame silently
+ (`adapterWs.ts`, the `isBinary` branch). The client sees a sequence gap and resyncs. The pane
+ flaps through "Restoring", and resync keyframes compete for the same socket.
+
+Only streams on the ws relay are affected. Streams on a p2p data channel (direct or TURN) never
+reach these guards. That explains why it shows up on some machines (a NAT'd or docker host, or after a
+p2p demotion) and not others.
+
+## Constraints that rule out the obvious fixes
+
+1. **The backend cannot count per stream.** Terminal JSON frames carry only `{__e2e: {v, k, n, ct}}`
+ (`isEncryptedTerminalFrame`), and binary frames carry the stream id inside the ciphertext. For the
+ same reason, a rejection cannot name a stream, so clients cannot scope the failure.
+2. **Over-budget acks cannot be dropped silently.** Acks are cumulative (`lastSeq`), but the host
+ pauses output at 384 KiB unacknowledged (`PAUSE_HIGH_WATERMARK_BYTES`). If the last ack of a
+ burst is dropped, the host closes the stream with `TERMINAL_RENDER_STALLED` after
+ `RENDER_STALL_TIMEOUT_MS`. That is the same Reconnect, only later.
+3. **The fix must work for clients already shipped.** Desktop, mobile and web all ack every 16 ms;
+ only a backend change reaches all of them at once.
+
+## Change
+
+In `backend/src/lib/terminalRelay.ts`:
+
+- Add `RELAY_BUSY_STREAMS = 16`: the number of streams with sustained output one socket must carry
+ without tripping. Sixteen covers four full four-pane tabs of one machine. A desk is rarely that
+ wide, and it leaves headroom for retained background tabs.
+- Derive the two limits from it, with the per-stream figures named next to it:
+ - `terminal_ack`: 16 × 3,750 = **60,000 frames/min**. Bytes: 8 MiB → **16 MiB**. A worst-case
+ E2EE ack frame is 216 B as `terminalFrameBytes` counts it (JSON of the frame, `ct` the base64 of
+ a 70 B payload plus the 16 B tag, with `lastSeq` and `n` at `Number.MAX_SAFE_INTEGER`), so 60,000
+ of them is ~13 MB. The test below pins that size.
+ - `terminal_output`: 16 × 7,500 = **120,000 frames/min**. Bytes stay at **128 MiB**: volume, not
+ frame count, is what the byte cap bounds, and today's figure is not what trips.
+- Rewrite the comments on both: the guard is per socket, the backend cannot see streams (E2EE), and
+ the numbers are per-stream rates times `RELAY_BUSY_STREAMS`.
+
+Unchanged:
+
+- Every other bucket. `terminal_sync` and `terminal_alive` run at 12/min per stream (5 s intervals),
+ so their limits fit about 100 streams. Clients debounce `terminal_resize` and `terminal_scroll`
+ (trailing timers), and the open/input/default buckets are human-paced.
+- Rejection semantics. Down: still `TERMINAL_FRAME_REJECTED`, which is fatal for the socket's
+ panes. Up: still a silent drop. Phases 2 and 3 revisit how failures are reported. This phase only
+ stops the legitimate traffic from being rejected.
+
+## Tests
+
+In `backend/src/lib/terminalRelay.test.ts`, next to "lets a busy renderer ack for a whole window":
+
+- `RELAY_BUSY_STREAMS` streams acking every 16 ms for a full minute (60,000 acks at the measured
+ frame size) all pass; the next one is refused.
+- The same for `terminal_output` at the 8 ms flush cadence (120,000 frames); the next one is refused.
+- The ack frame size used above is not a guess. The test builds a real `terminal_ack` frame wrapped
+ the way the client wraps it (an `__e2e` envelope with a base64 `ct` of a `{streamId, lastSeq}` payload
+ plus tag) and asserts `terminalFrameBytes` × 60,000 fits the byte cap. A later change that fattens
+ the frame then fails here, not in production.
+- The existing single-stream test stays as it is.
+
+Validation: the backend's affected unit tests (`terminalRelay.test.ts`, plus the `webWs`/`adapterWs`
+suites that construct the guard). PR CI runs the backend component checks. No CLI coverage gates or
+client suites are involved.
+
+## Rollout
+
+Backend only. A deploy restarts adapter and web sockets (close 1012). That is the Phase 2 problem,
+and until Phase 2 lands it drops remote terminals once more during this rollout. After the deploy,
+every client already shipped stops tripping the guard with up to 16 busy streams per socket.
+
+Check after deploy: on a remote machine reached over the ws relay (p2p off or failed), run steady
+output in four panes for two minutes. No pane should show Reconnect or flap through Restoring.
+
+## Trade-off
+
+A compromised or buggy daemon or client can push about 6× more ack and output frames per minute to
+Redis before the guard stops it. The output byte cap is unchanged, and the ack byte cap doubles to
+16 MiB/min. That is the price of not breaking legitimate multi-pane use. Cutting ack frequency on the
+clients (one ack per 64 KiB or ~250 ms) would recover most of it, and is deferred until Redis load
+says it matters.
+
+## Out of scope
+
+- Client ack cadence (option B of the investigation).
+- Phase 2: a host's `linkDown` closes p2p-carried streams silently (`backendSocket.ts:378`). Resync
+ for a stream that no longer exists is ignored instead of answered with `TERMINAL_STREAM_NOT_FOUND`.
+ The desktop makes one reopen attempt and then waits for a `node_status` change that may never
+ come.
+- Phase 3: `TerminalSession` failure reasons go to `debugPrint` only, not to
+ `~/.harness/logs/app-*.log`.