Commit 3bbbc1d9fd8b3d649c60ba0137c7dae93a6aab3f | the-knife

author	Theo Browne <me@t3.gg> 2026-09-04 08:31:17-07:00
committer	GitHub <noreply@github.com> 2026-09-04 08:31:17-07:00
log	3bbbc1d9fd8b3d649c60ba0137c7dae93a6aab3f
tree	235922a2a70bf9cd5cfa4bdaded8eb37f6256191
parent	010d6bb1b5281cb1e6eacf1ee0f2500973242836
signature	Signed by PGP key B5690EEEBB952194

perf(server): stop rebuilding terminal history per chunk (#9703)

Append terminal history incrementally and materialize text for snapshots and coalesced disk writes.
Clear evicted line references without changing retained output.

Continues [#9357](https://github.com/pingdotgg/t3code/pull/9357). The original contribution and author credit are preserved.
The current line limit and wire format stay unchanged. A strict byte limit remains separate work.

Created with GPT-6 Astra (preview) in Codex.

Co-authored-by: will <will@moondiner.com>

3 files changed, 216 insertions(+), 26 deletions(-)

apps
- server
  - src
    terminal
    Manager.test.ts
    Manager.ts
docs
- internals
  - terminal-runtime.md

apps/server/src/terminal/Manager.test.ts+83

...	@@ -276,6 +276,70 @@ const createManager = (	...	@@ -276,6 +276,70 @@ const createManager = (
276	const withHostPlatform = (platform: NodeJS.Platform) =>	276	const withHostPlatform = (platform: NodeJS.Platform) =>
277	Layer.succeed(HostProcessPlatform, platform);	277	Layer.succeed(HostProcessPlatform, platform);
278		278
		279	// The previous split/join algorithm is the reference for retained text.
		280	function retainedHistory(text: string, maxLines: number): string {
		281	const terminated = text.endsWith("\n");
		282	const lines = text.split("\n");
		283	if (terminated) lines.pop();
		284	const retained = lines.slice(Math.max(0, lines.length - maxLines)).join("\n");
		285	return terminated ? `${retained}\n` : retained;
		286	}
		287
		288	it("preserves history across arbitrary chunks, Unicode, ANSI sequences, and clear", () => {
		289	let randomSeed = 0x20260904;
		290	const fragments = [
		291	"",
		292	"a",
		293	"\n",
		294	"\n\n",
		295	"\r",
		296	"\r\n",
		297	"café",
		298	"名",
		299	"🚀",
		300	"\u001b[31m",
		301	"\u001b[0m",
		302	"\u001b]8;;url\u0007",
		303	"\ud83d",
		304	"\ude80",
		305	];
		306	const nextFragment = () => {
		307	randomSeed = (Math.imul(randomSeed, 1_664_525) + 1_013_904_223) >>> 0;
		308	return fragments[randomSeed % fragments.length]!;
		309	};
		310
		311	for (const maxLines of [0, 1, 3, 5, 5_000]) {
		312	let expected = retainedHistory("before\ninitial\n", maxLines);
		313	const history = new TerminalManager.BoundedTerminalHistory(maxLines, expected);
		314	expect(history.value()).toBe(expected);
		315
		316	for (let step = 0; step < 300; step += 1) {
		317	if (step % 73 === 0) {
		318	history.clear();
		319	expected = "";
		320	expect(history.value()).toBe(expected);
		321	}
		322	const chunk = nextFragment() + nextFragment();
		323	history.append(chunk);
		324	expected = retainedHistory(expected + chunk, maxLines);
		325	expect(history.value()).toBe(expected);
		326	}
		327	}
		328	});
		329
		330	it("preserves retained lines as older storage is compacted", () => {
		331	for (const maxLines of [3, 5_000]) {
		332	let expected = "";
		333	const history = new TerminalManager.BoundedTerminalHistory(maxLines, expected);
		334	for (let batch = 0; batch < 40; batch += 1) {
		335	const chunk = Array.from({ length: 300 }, (_, line) => `${batch}:${line}\n`).join("");
		336	history.append(chunk);
		337	expected = retainedHistory(expected + chunk, maxLines);
		338	expect(history.value()).toBe(expected);
		339	}
		340	}
		341	});
		342
279	it.layer(	343	it.layer(
280	Layer.merge(NodeServices.layer, ProcessRunner.layer.pipe(Layer.provide(NodeServices.layer))),	344	Layer.merge(NodeServices.layer, ProcessRunner.layer.pipe(Layer.provide(NodeServices.layer))),
281	{ excludeTestServices: true },	345	{ excludeTestServices: true },
...	@@ -1090,6 +1154,25 @@ it.layer(	...	@@ -1090,6 +1154,25 @@ it.layer(
1090	}),	1154	}),
1091	);	1155	);
1092		1156
		1157	it.effect("caps incrementally appended history without losing partial or empty lines", () =>
		1158	Effect.gen(function* () {
		1159	const { manager, ptyAdapter } = yield* createManager(3);
		1160	yield* manager.open(openInput());
		1161	const process = ptyAdapter.processes[0];
		1162	expect(process).toBeDefined();
		1163	if (!process) return;
		1164
		1165	process.emitData("line1\n");
		1166	process.emitData("\n");
		1167	process.emitData("line3");
		1168	process.emitData("-continued\nline4");
		1169	yield* manager.close({ threadId: "thread-1" });
		1170
		1171	const reopened = yield* manager.open(openInput());
		1172	expect(reopened.history).toBe("\nline3-continued\nline4");
		1173	}),
		1174	);
		1175
1093	it.effect("strips replay-unsafe terminal query and reply sequences from persisted history", () =>	1176	it.effect("strips replay-unsafe terminal query and reply sequences from persisted history", () =>
1094	Effect.gen(function* () {	1177	Effect.gen(function* () {
1095	const { manager, ptyAdapter } = yield* createManager();	1178	const { manager, ptyAdapter } = yield* createManager();

apps/server/src/terminal/Manager.ts+85-26

 @@ -238,14 +238,14 @@ export interface TerminalStartInput extends TerminalOpenInput {
   rows: number;
 }
-export interface TerminalSessionState {
+interface TerminalSessionState {
   threadId: string;
   terminalId: string;
   cwd: string;
   worktreePath: string | null;
   status: TerminalSessionStatus;
   pid: number | null;
-  history: string;
+  history: BoundedTerminalHistory;
   pendingHistoryControlSequence: string;
   pendingProcessEvents: Array<PendingProcessEvent>;
   pendingProcessEventIndex: number;
 @@ -266,7 +266,7 @@ export interface TerminalSessionState {
 }
 interface PersistHistoryRequest {
-  history: string;
+  history: BoundedTerminalHistory;
   immediate: boolean;
 }
 @@ -281,7 +281,7 @@ type DrainProcessEventAction =
       threadId: string;
       terminalId: string;
       sequence: number;
-      history: string | null;
+      history: BoundedTerminalHistory | null;
       data: string;
     }
   | {
 @@ -340,7 +340,7 @@ function snapshot(session: TerminalSessionState): TerminalSessionSnapshot {
     worktreePath: session.worktreePath,
     status: session.status,
     pid: session.pid,
-    history: session.history,
+    history: session.history.value(),
     exitCode: session.exitCode,
     exitSignal: session.exitSignal,
     label: terminalWireLabel(session),
 @@ -796,6 +796,66 @@ function capHistory(history: string, maxLines: number): string {
   return hasTrailingNewline ? `${capped}\n` : capped;
 }
+export class BoundedTerminalHistory {
+  private readonly maxLines: number;
+  private lines: Array<string>;
+  private start = 0;
+  private trailingNewline: boolean;
+  private cachedValue: string | null = null;
+  constructor(maxLines: number, initial: string) {
+    this.maxLines = maxLines;
+    const capped = capHistory(initial, maxLines);
+    this.trailingNewline = capped.endsWith("\n");
+    this.lines = capped.length === 0 ? [] : capped.split("\n");
+    if (this.trailingNewline) this.lines.pop();
+  }
+  append(text: string): void {
+    if (text.length === 0) return;
+    const trailingNewline = text.endsWith("\n");
+    const appendedLines = text.split("\n");
+    if (trailingNewline) appendedLines.pop();
+    const activeLines = this.lines.length - this.start;
+    if (activeLines === 0 || this.trailingNewline) {
+      for (const line of appendedLines) this.lines.push(line);
+    } else {
+      this.lines[this.lines.length - 1] += appendedLines[0] ?? "";
+      for (let index = 1; index < appendedLines.length; index += 1) {
+        this.lines.push(appendedLines[index] ?? "");
+      }
+    }
+    this.trailingNewline = trailingNewline;
+    const overflow = this.lines.length - this.start - this.maxLines;
+    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;
+    }
+    this.cachedValue = null;
+  }
+  clear(): void {
+    this.lines = [];
+    this.start = 0;
+    this.trailingNewline = false;
+    this.cachedValue = "";
+  }
+  value(): string {
+    if (this.cachedValue !== null) return this.cachedValue;
+    const joined = this.lines.slice(this.start).join("\n");
+    this.cachedValue = this.trailingNewline ? `${joined}\n` : joined;
+    return this.cachedValue;
+  }
+}
 function isCsiFinalByte(codePoint: number): boolean {
   return codePoint >= 0x40 && codePoint <= 0x7e;
 }
 @@ -1372,22 +1432,24 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
         return;
       }
-      yield* fileSystem.writeFileString(historyPath(threadId, terminalId), request.history).pipe(
+      yield* fileSystem
-        Effect.catch((error) =>
+        .writeFileString(historyPath(threadId, terminalId), request.history.value())
-          Effect.logWarning("failed to persist terminal history", {
+        .pipe(
-            threadId,
+          Effect.catch((error) =>
-            terminalId,
+            Effect.logWarning("failed to persist terminal history", {
-            error,
+              threadId,
-          }),
+              terminalId,
-        ),
+              error,
-      );
+            }),
+          ),
+        );
     }),
   });
   const queuePersist = Effect.fn("terminal.queuePersist")(function* (
     threadId: string,
     terminalId: string,
-    history: string,
+    history: BoundedTerminalHistory,
   ) {
     yield* persistWorker.enqueue(toSessionKey(threadId, terminalId), {
       history,
 @@ -1405,7 +1467,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
   const persistHistory = Effect.fn("terminal.persistHistory")(function* (
     threadId: string,
     terminalId: string,
-    history: string,
+    history: BoundedTerminalHistory,
   ) {
     yield* persistWorker.enqueue(toSessionKey(threadId, terminalId), {
       history,
 @@ -1661,10 +1723,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
           );
           session.pendingHistoryControlSequence = sanitized.pendingControlSequence;
           if (sanitized.visibleText.length > 0) {
-            session.history = capHistory(
+            session.history.append(sanitized.visibleText);
-              `${session.history}${sanitized.visibleText}`,
-              historyLineLimit,
-            );
           }
           const eventStamp = advanceEventSequence(session);
 @@ -2160,7 +2219,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
         worktreePath: input.worktreePath ?? null,
         status: "starting",
         pid: null,
-        history,
+        history: new BoundedTerminalHistory(historyLineLimit, history),
         pendingHistoryControlSequence: "",
         pendingProcessEvents: [],
         pendingProcessEventIndex: 0,
 @@ -2221,7 +2280,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
       liveSession.cwd = input.cwd;
       liveSession.worktreePath = nextWorktreePath;
       liveSession.runtimeEnv = nextRuntimeEnv;
-      liveSession.history = "";
+      liveSession.history.clear();
       liveSession.pendingHistoryControlSequence = "";
       liveSession.pendingProcessEvents = [];
       liveSession.pendingProcessEventIndex = 0;
 @@ -2230,7 +2289,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
     } else if (liveSession.status === "exited" || liveSession.status === "error") {
       liveSession.runtimeEnv = nextRuntimeEnv;
       liveSession.worktreePath = nextWorktreePath;
-      liveSession.history = "";
+      liveSession.history.clear();
       liveSession.pendingHistoryControlSequence = "";
       liveSession.pendingProcessEvents = [];
       liveSession.pendingProcessEventIndex = 0;
 @@ -2535,7 +2594,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
       Effect.gen(function* () {
         const terminalId = input.terminalId;
         const session = yield* requireSession(input.threadId, terminalId);
-        session.history = "";
+        session.history.clear();
         session.pendingHistoryControlSequence = "";
         session.pendingProcessEvents = [];
         session.pendingProcessEventIndex = 0;
 @@ -2572,7 +2631,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
             worktreePath: input.worktreePath ?? null,
             status: "starting",
             pid: null,
-            history: "",
+            history: new BoundedTerminalHistory(historyLineLimit, ""),
             pendingHistoryControlSequence: "",
             pendingProcessEvents: [],
             pendingProcessEventIndex: 0,
 @@ -2608,7 +2667,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
         const cols = input.cols ?? session.cols;
         const rows = input.rows ?? session.rows;
-        session.history = "";
+        session.history.clear();
         session.pendingHistoryControlSequence = "";
         session.pendingProcessEvents = [];
         session.pendingProcessEventIndex = 0;

docs/internals/terminal-runtime.md created+48

...	@@ -0,0 +1,48 @@
1	# Terminal runtime
2
3	The environment server owns terminal processes, retained output history, and
4	session lifecycle. Web, desktop, and mobile clients attach to the same
5	server-owned session over the environment RPC connection. The desktop renderer
6	does not own a separate PTY. Clients can reconnect to a running PTY or share
7	it with another client.
8
9	## Output path
10
11	PTY output follows this path:
12
13	```text
14	PTY callback
15	-> ordered process-event drain
16	-> bounded retained-history append
17	-> live terminal output event
18	-> coalesced history persistence
19	```
20
21	Live output events contain only the new PTY data. Full retained history is
22	materialized only when the server returns a snapshot or when the coalescing
23	persistence worker writes the latest state.
24
25	Retained history uses an incremental bounded line buffer. Appending one PTY
26	chunk may scan and allocate for that new chunk, but it must not split, join, or
27	copy the entire retained history for every callback. Empty lines, incomplete
28	final lines, trailing newlines, and the configured line limit are preserved
29	exactly when history is materialized.
30
31	Discard each line's string reference as soon as the line leaves retained
32	history. Array compaction can run later.
33
34	The server's line limit does not limit the byte size of retained history.
35	Shared web and mobile client state currently retains at most 512 KiB. A server
36	byte limit would change persisted scrollback and needs a separate retention
37	decision.
38
39	Measure sustained-output changes against a full retained history so terminal
40	throughput does not regress unnoticed.
41
42	## Persistence
43
44	History persistence is keyed by terminal session and coalesces pending writes.
45	The worker reads the newest bounded-history state after its debounce instead
46	of receiving a newly materialized full string for every PTY callback. Clear,
47	restart, close, and final flush operations still force the latest state to
48	disk before their lifecycle boundary completes.