[nedtwigg]

Draft, for the maintainer's read. Audit finding session-03: nothing between the PTY and xterm.js applied backpressure.

The problem

Every chunk of PTY output was pushed into xterm with no accounting. xterm parses in 12 ms slices and throws write data discarded once 50,000,000 chars wait unparsed. So a flood (yes, a runaway print loop), or ordinary output into a window whose timers are throttled (a minimized standalone window on Windows or Linux), queued without bound, then lost output and raised an uncaught error per chunk.

Measured in real Chrome through the innerdogfood harness with acknowledgements disabled, which is the old behavior: yes filled xterm's queue to the 50 M discard within 4 seconds, and Ctrl+C had not reached a prompt after 2 minutes.

The design

The scheme VS Code's own terminal uses: acknowledged characters, and the host decides.

1. The renderer acknowledges what it parsed. Every char of live pty:data is acknowledged exactly once: from xterm's write callback in batches, or at once when no terminal took it or xterm refused it. Never from a timer, so a throttled window acknowledges as fast as it parses. Replays are not counted.

2. The host counts and pauses. Each Node-resident host keeps, per PTY, chars sent minus chars acknowledged. Above the high watermark it pauses node-pty, the kernel buffer fills and the program's write blocks; at the low watermark it resumes.

3. The host owns recovery. The debt is forgiven and the PTY resumed on a requestInit, a transfer mark, a spawn over the id, a VS Code view going away, and the recovery capture's interrupt. A PTY never stays paused because an acknowledgement was lost.

4. Input reaches a paused program. On macOS and Linux the kernel delivers an interrupt to a blocked program by itself. On Windows it cannot: the console host stops taking input while it is blocked on a full output pipe (see below). So on Windows any input written to a paused PTY resumes reading, pausing again after 250 ms without input, with a hard ceiling at twice the high watermark so memory stays bounded however much input arrives, from a keyboard or a phone.

5. Only the local renderer exerts backpressure. A phone can never pause a PTY on the laptop; Pocket's and the fake adapter's acknowledgePtyData are no-ops. The remote path's own bounds are Remote control: coalesce terminal output to a phone, and bound what the Relay queues for a stalled socket #1721.

6. terminal.write is wrapped so a throw cannot escape the dispatch loop, and a refused chunk is still acknowledged.

7. A hidden or starved renderer parses on arrival, not on timers. xterm only parses from a timer, and a hidden page's timers are throttled: in a Chrome tab hidden for over a minute, a renderer with a backlog parsed about 540 chars/s. Pacing alone would therefore stall a program in a minimized window on Windows or Linux once it got ahead, and a phone attached to that pane with it. So when the page is hidden, when the host says its view is not shown (VS Code keeps a hidden webview alive and such a page still reports visible), or when a write has waited 250 ms with no parse progress, each arriving chunk parses one slice synchronously; message delivery is not throttled. It hands back to xterm's timers once the queue is empty and the page is visible, so a healthy visible window is untouched. Measured hidden for 7 minutes under yes: 9.2 M chars/s with the queue at most 1 KB. In a hidden tab forced to report visible, the 250 ms starvation trigger alone gives 3.2 to 4.4 M chars/s (a 1 s threshold went quiet at 45 to 70 K chars/s, because each once-a-second wake finished a write). A visible yes is unchanged: about 12 M chars/s at 60 fps, p95 frame 17 ms; parsing on arrival always would cost frames (36 fps), which is why it is conditional. The reach into xterm's internals (_innerWrite, _parseStack.paused) lives in one module, lib/src/lib/xterm-write-slice.ts, which feature-detects them and falls back to timers with one warning; a test pins their shape against the installed xterm, so a bump cannot silently turn this off.

New message pty:ack (pty_ack in standalone), { id, chars }; new required PlatformAdapter.acknowledgePtyData. Rules are in docs/specs/transport.md -> "Output flow control".

Numbers

Constants: acknowledge every 262,144 chars; resume at 1,048,576; pause at 2,097,152. At most about 4.2 MB is held per terminal.

	Before	After
yes in real Chrome: xterm's queue	50 M chars (discard) within 4 s	Stays under 1.84 M chars
Ctrl+C on a yes flood (real node-pty)	4 to 25 s	48 to 77 ms
Ctrl+C in real Chrome	No prompt after 2 minutes	128 ms
Throughput, 80-column log lines	Baseline	Within 4% at 2 ms each way; 19% slower at 5 ms

VS Code's own constants (acknowledge every 5,000, pause at 100,000) cost 55% on log lines over this IPC, which is why they are larger here.

The trade-off for a phone

A paused PTY slows every viewer, a phone included, and a phone is usually in use because the laptop is unattended. Parse on arrival is what keeps that from mattering: a minimized window or a hidden view keeps up, so it does not pause its PTYs. What remains by design is a renderer that is truly hung: its PTYs stay paused for every viewer until it is reloaded or closed.

Where the design bent

• The counter is not in pty-core. The renderer can only acknowledge the parsed data, and the host-side parse strips OSCs, so a raw count would never be paid back. It sits where each host sends pty:data (lib/src/host/pty-flow-host.ts): the sidecar, and VS Code's extension host, which tells its pty-host child to pause.
• Standalone's Rust acknowledges output it drops (mid-transfer, or no owner), or a suppressed transfer would leave the PTY paused.
• macOS reads a paused PTY once every 150 ms. When a PTY's only process exits while paused, macOS holds the exit about 610 ms and then discards everything past the first 1 KB of unread output (reproduced with cat, zsh -c, python3, perl and node as the leader). The periodic read lets the exit through with its tail; it stops at the same ceiling of twice the high watermark as the Windows input rule. A test with a 1,500-char tail fails without it.

Independent review

A second agent with no part in writing this reviewed the branch read-only. It found no path on which a PTY stays paused forever, no counting drift, and one unit (UTF-16 code units of data) at every hop. Its findings, all fixed here: the macOS loss above was wider than first claimed; nothing tested that Rust acknowledges what it drops (deleting the call left every test green); a long paced dor send could outlive the Windows input grace; the spec's stated bound was wrong once the grace existed; CI's Windows leg did not run the real-PTY cases. Its last point, that a hidden window would pace its programs to throttled timers, is what item 7 answers.

Tests

Each was run against origin/main and fails there: four lib tests (batched acknowledgement, an unconsumed chunk, a throwing write, replays), eight real-node-pty sidecar tests (six can fail on old code, for example "expected 40500000 to be ≤ 165536"), five VS Code manager and router tests plus a real-PTY test of pty-host.js, and the Rust drop-acknowledgement and adapter tests. A compile-time check fails tsc -b if acknowledgePtyData becomes optional.

Suites: lib 7180, standalone 323, sidecar 254, vscode-ext 275, cargo 182.

Windows, on a real machine

Run by hand on Windows 11 (node-pty 1.2.0-beta.18, ConPTY through conpty.dll), since CI's Windows leg does not run these files.

• The first run found that Ctrl+C does not reach a program whose PTY is paused. A probe separated the causes: never paused, the child exits 14 to 17 ms after \x03 or the win32-input-mode key record; paused and left paused, it is still alive after 2,500 ms with nothing read; paused and then resumed, it exits in 16 ms after about 290 K chars are read. The Windows input rule above is the fix (6f6dbec59).
• After it: standalone/src/sidecar-flow-control.test.ts passes 7 of 7 three runs in a row (one case is POSIX-only and skipped), vscode-ext/test/pty-host-flow.test.ts passes, and the rule's unit tests pass.
• CI's Linux leg runs the real-PTY sidecar tests and is green.

Not verified

• Whether Tauri's webview reports hidden when minimized on Windows and Linux. If it does not, the starvation trigger takes over; that path is measured in a hidden Chrome tab forced to report visible, not observed in a real minimized Tauri window. VS Code's hidden view is covered by the host's own signal.
• An inline image whose decode takes over 12 ms resumes on xterm's timer, one throttled wake per image, while hidden.
• A real Tauri window, and a minimized one on Windows or Linux, the case that motivated this: pnpm dev:standalone, run yes, minimize for a minute, restore. The log should show no dropped output, and Ctrl+C should give a prompt within a second.
• transport.md's word budget is re-baselined from 4700 to 5050 for the new section.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying mouseterm with    Cloudflare Pages

Latest commit:	9c8a59a
Status:	✅  Deploy successful!
Preview URL:	https://012329e9.mouseterm.pages.dev
Branch Preview URL:	https://flow-control.mouseterm.pages.dev

View logs

[dormouse-bot]

A hidden VS Code view now throttles its programs, not just its rendering. The extension keeps webviews alive when hidden (retainContextWhenHidden: true in vscode-ext/src/extension.ts), and transport.rationale.md -> "Why not the webview" notes that a hidden webview's timers fire about once a second. xterm parses in 12 ms slices that a timer re-arms, so a hidden view parses roughly one slice per second. At the 10.8 M chars/s this PR measured for a visible page, that comes to around 130 K chars/s. That figure is my extrapolation, not a measurement. Before this change, output from a PTY in a hidden panel queued in the webview and the program ran at full speed. Now, once a hidden view owes 2 M chars, sentOutput -> pause blocks the program's write until the view catches up. A verbose build, a test run, or an agent printing heavily in a collapsed Dormouse panel slows to that rate for as long as the panel stays hidden. If Chromium's intensive throttling applies to the hidden frame, it slows further. VS Code's own terminal doesn't do this: its renderer runs in the visible workbench window, so the scheme it borrows never sees a throttled renderer.

The PR names the macOS tail loss as the main trade-off but doesn't mention this one. It applies to every VS Code user, not only to a flood racing an exit. Minimized standalone windows on Windows and Linux are the same case, already listed under "Not verified". A measurement would settle how large the effect is: time seq 1 5000000 printed to the terminal in a hidden panel versus a visible one. If it is significant, the host already knows when a view is hidden (the shown port in webview-view-provider.ts / extension.ts). It could forgive the debt while the view is hidden and resume counting when it is shown again. Whether to do that is a maintainer's call between bounded memory and background throughput.

[dormouse-bot]

This push turns the spec's "a Client's stream is never paced" into "a PTY it pauses slows every viewer, a Client's stream too". That makes the laptop's renderer the pace of a phone session, and it slows down exactly when nobody is at the laptop. The note is on the spec line.

[dormouse-bot]

parseOnArrival only treats the page as hidden when document.hidden is true. The hidden VS Code view this push answers usually doesn't report that. VS Code's extension posts dormouse:shown for this reason, and lib/src/lib/host-shown.ts exists for it too. That leaves the starvation trigger to cover the case, which the PR's "Not verified" already flags. Under a 1 Hz timer throttle the trigger is borderline: every throttled wake finishes a write and resets progressAt, so an arrival rarely sees a full PARSE_STARVED_MS gap, and parsing stays at one slice per wake. That's my inference, not a measurement. Checking hostShown() beside document.hidden covers the view without depending on the threshold; suggestion inline.