@@ -276,6 +276,70 @@ const createManager = (
 const withHostPlatform = (platform: NodeJS.Platform) =>
   Layer.succeed(HostProcessPlatform, platform);
 
+// The previous split/join algorithm is the reference for retained text.
+function retainedHistory(text: string, maxLines: number): string {
+  const terminated = text.endsWith("\n");
+  const lines = text.split("\n");
+  if (terminated) lines.pop();
+  const retained = lines.slice(Math.max(0, lines.length - maxLines)).join("\n");
+  return terminated ? `${retained}\n` : retained;
+}
+
+it("preserves history across arbitrary chunks, Unicode, ANSI sequences, and clear", () => {
+  let randomSeed = 0x20260904;
+  const fragments = [
+    "",
+    "a",
+    "\n",
+    "\n\n",
+    "\r",
+    "\r\n",
+    "café",
+    "名",
+    "🚀",
+    "\u001b[31m",
+    "\u001b[0m",
+    "\u001b]8;;url\u0007",
+    "\ud83d",
+    "\ude80",
+  ];
+  const nextFragment = () => {
+    randomSeed = (Math.imul(randomSeed, 1_664_525) + 1_013_904_223) >>> 0;
+    return fragments[randomSeed % fragments.length]!;
+  };
+
+  for (const maxLines of [0, 1, 3, 5, 5_000]) {
+    let expected = retainedHistory("before\ninitial\n", maxLines);
+    const history = new TerminalManager.BoundedTerminalHistory(maxLines, expected);
+    expect(history.value()).toBe(expected);
+
+    for (let step = 0; step < 300; step += 1) {
+      if (step % 73 === 0) {
+        history.clear();
+        expected = "";
+        expect(history.value()).toBe(expected);
+      }
+      const chunk = nextFragment() + nextFragment();
+      history.append(chunk);
+      expected = retainedHistory(expected + chunk, maxLines);
+      expect(history.value()).toBe(expected);
+    }
+  }
+});
+
+it("preserves retained lines as older storage is compacted", () => {
+  for (const maxLines of [3, 5_000]) {
+    let expected = "";
+    const history = new TerminalManager.BoundedTerminalHistory(maxLines, expected);
+    for (let batch = 0; batch < 40; batch += 1) {
+      const chunk = Array.from({ length: 300 }, (_, line) => `${batch}:${line}\n`).join("");
+      history.append(chunk);
+      expected = retainedHistory(expected + chunk, maxLines);
+      expect(history.value()).toBe(expected);
+    }
+  }
+});
+
 it.layer(
   Layer.merge(NodeServices.layer, ProcessRunner.layer.pipe(Layer.provide(NodeServices.layer))),
   { excludeTestServices: true },
 
@@ -796,7 +796,7 @@ function capHistory(history: string, maxLines: number): string {
   return hasTrailingNewline ? `${capped}\n` : capped;
 }
 
-class BoundedTerminalHistory {
+export class BoundedTerminalHistory {
   private readonly maxLines: number;
   private lines: Array<string>;
   private start = 0;
@@ -830,7 +830,10 @@ class BoundedTerminalHistory {
     this.trailingNewline = trailingNewline;
 
     const overflow = this.lines.length - this.start - this.maxLines;
-    if (overflow > 0) this.start += overflow;
+    if (overflow > 0) {
+      this.lines.fill("", this.start, this.start + overflow);
+      this.start += overflow;
+    }
     if (this.start > 2_048 && this.start * 2 >= this.lines.length) {
       this.lines = this.lines.slice(this.start);
       this.start = 0;
 
@@ -1,10 +1,10 @@
 # Terminal runtime
 
 The environment server owns terminal processes, retained output history, and
-session lifecycle. Web and desktop clients attach to the same server-owned
-session over the environment RPC connection. Desktop must not replace this
-with a renderer-owned PTY: reconnect, remote access, and multi-client attach
-all depend on the environment remaining authoritative.
+session lifecycle. Web, desktop, and mobile clients attach to the same
+server-owned session over the environment RPC connection. The desktop renderer
+does not own a separate PTY. Clients can reconnect to a running PTY or share
+it with another client.
 
 ## Output path
 
@@ -18,8 +18,8 @@ PTY callback
   -> coalesced history persistence
 ```
 
-Live output events contain only the new PTY data. A full retained-history
-snapshot is materialized only when a client attaches or when the coalescing
+Live output events contain only the new PTY data. Full retained history is
+materialized only when the server returns a snapshot or when the coalescing
 persistence worker writes the latest state.
 
 Retained history uses an incremental bounded line buffer. Appending one PTY
@@ -28,19 +28,21 @@ copy the entire retained history for every callback. Empty lines, incomplete
 final lines, trailing newlines, and the configured line limit are preserved
 exactly when history is materialized.
 
-This is a performance invariant, not an implementation detail to discard
-during refactors. Measure sustained-output changes against a full retained
-history so terminal throughput does not regress unnoticed.
+Discard each line's string reference as soon as the line leaves retained
+history. Array compaction can run later.
 
-## Persistence and transport changes
+The server's line limit does not limit the byte size of retained history.
+Shared web and mobile client state currently retains at most 512 KiB. A server
+byte limit would change persisted scrollback and needs a separate retention
+decision.
+
+Measure sustained-output changes against a full retained history so terminal
+throughput does not regress unnoticed.
+
+## Persistence
 
 History persistence is keyed by terminal session and coalesces pending writes.
 The worker reads the newest bounded-history state after its debounce instead
 of receiving a newly materialized full string for every PTY callback. Clear,
 restart, close, and final flush operations still force the latest state to
 disk before their lifecycle boundary completes.
-
-If measurements later justify a binary terminal data channel, keep snapshots,
-lifecycle commands, and PTY ownership on the environment server. Do not share
-the terminal data channel with port-forward payloads: a bulk TCP transfer must
-not head-of-line block interactive terminal input or output.