1# Terminal runtime
2
3The environment server owns PTYs, session lifetime, and retained output. Every
4client, including the desktop renderer, attaches through the environment connection.
5This lets clients reconnect or share a running session. Renderer choices stay local
6to each client and do not change terminal contracts.
7
8## Output and retention
9
10[Terminal history](../../apps/server/src/terminal/Manager.ts) is incremental.
11PTY callbacks append new chunks; live events carry only those chunks. Materializing
12or copying full scrollback on every callback makes output cost grow with retained
13history, so snapshots and coalesced persistence are the materialization boundaries.
14Persistence queues the mutable history buffer and reads its latest value when the
15write runs. Clear, restart, and close must drain writes before completing their
16lifecycle boundary.
17
18Server history is capped at 5,000 lines and 8 MiB of UTF-8 text per terminal, so a
19long unterminated line cannot bypass retention. Eviction removes the oldest output
20without splitting Unicode code points; live output is not truncated. Release
21discarded chunk references immediately, even if array compaction happens later.
22Client buffers have a separate 512 KiB cap. Measure throughput with full scrollback
23when changing this path.
24
25Restoration must read only the bounded tail of current or legacy history files,
26skip any incomplete UTF-8 prefix, and apply the line limit. Close the read handle
27before rewriting the capped file. Reading whole old logs would defeat the memory
28bound during startup.
29
30## Renderer ownership
31
32Android and web use the same `libghostty-vt` C ABI for terminal behavior. Platform
33adapters own drawing and input integration, and React stays out of terminal frames.
34The web adapter shares one WebAssembly instance per browser tab while each terminal
35owns and frees its own handles. The canonical upstream pin is
36[`native/libghostty-vt/VERSION`](../../native/libghostty-vt/VERSION); both native and
37web artifacts must be rebuilt when it changes. Web embeds the revision in its build
38info so the ABI check can detect drift without a second pin.
39
40Restoring scrollback must not send terminal replies to the current shell. Historical
41device queries can otherwise provoke fresh replies that appear as junk at the
42prompt. The server strips query/response traffic from retained history, and the
43[web renderer](../../apps/web/src/terminal/ghostty/core.ts) detaches its PTY writer
44during replay. Preserve both protections when changing retention or renderer code.