The best way to control Claude Code, Codex and more from any computer or phone
fix(server): persist terminal output without rewriting all history (#24019)
Co-authored-by: maria-rcks <maria@kuuro.net> Co-authored-by: Julius Marminge <julius0216@outlook.com>
Yukun Shan committed
Nov 13, 2026 at 06:46 UTC
65716ba1d7a78171bf11fbc1f11660cdd938b588
2 files changed
+226
-12
apps/server/src/terminal/Manager.test.ts
+149
@@ -28,6 +28,7 @@ import * as PlatformError from "effect/PlatformError";
28
import * as Path from "effect/Path";
29
import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
30
import * as Ref from "effect/Ref";
31
+import * as Queue from "effect/Queue";
32
import * as Schema from "effect/Schema";
33
import * as Scope from "effect/Scope";
34
import * as Stream from "effect/Stream";
@@ -409,6 +410,41 @@ it("bounds long partial lines and joins surrogate pairs across chunk boundaries"
410
}
411
});
412
413
+it("restores bounded history across append compaction, clears and split Unicode", () => {
414
+ const maxBytes = 64;
415
+ const history = new TerminalManager.BoundedTerminalHistory(3, "", maxBytes);
416
+ let cursor: ReturnType<typeof history.persistenceUpdate>["cursor"] | undefined;
417
+ let persisted = "";
418
+ let compactions = 0;
419
+ const flush = () => {
420
+ const update = history.persistenceUpdate(cursor);
421
+ if (!update.append) compactions += 1;
422
+ const encoded = Buffer.from(update.data).toString();
423
+ persisted = update.append ? persisted + encoded : encoded;
424
+ cursor = update.cursor;
425
+ expect(Buffer.byteLength(persisted)).toBeLessThanOrEqual(maxBytes * 2);
426
+ expect(retainedHistory(persisted, 3, maxBytes)).toBe(Buffer.from(history.value()).toString());
427
+ };
428
+ for (let index = 0; index < 100; index += 1) {
429
+ history.append(`line ${index} 名\n`);
430
+ flush();
431
+ }
432
+ expect(compactions).toBeGreaterThan(1);
433
+ expect(compactions).toBeLessThan(50);
434
+ history.clear();
435
+ flush();
436
+ expect(persisted).toBe("");
437
+ history.append("\ud83d");
438
+ flush();
439
+ history.append("\ude80");
440
+ flush();
441
+ expect(persisted).toBe("🚀");
442
+ // More output than the retained window between flushes must replace the file.
443
+ history.append("z".repeat(maxBytes * 3));
444
+ flush();
445
+ expect(persisted).toBe("z".repeat(maxBytes));
446
+});
447
+
448
it.layer(
449
Layer.mergeAll(
450
NodeServices.layer,
@@ -1045,6 +1081,119 @@ it.layer(
1081
}),
1082
);
1083
1084
+ it.effect("persists small terminal updates without rewriting the retained history", () =>
1085
+ Effect.gen(function* () {
1086
+ const fs = yield* FileSystem.FileSystem;
1087
+ const writes = yield* Queue.unbounded<number>();
1088
+ const maxBytes = 64 * 1024;
1089
+ const { manager, ptyAdapter, logsDir } = yield* createManager(5_000, {
1090
+ historyByteLimit: maxBytes,
1091
+ }).pipe(
1092
+ Effect.provideService(FileSystem.FileSystem, {
1093
+ ...fs,
1094
+ writeFileString: (path, data, options) =>
1095
+ fs
1096
+ .writeFileString(path, data, options)
1097
+ .pipe(
1098
+ Effect.tap(() =>
1099
+ data.length > 0 ? Queue.offer(writes, Buffer.byteLength(data)) : Effect.void,
1100
+ ),
1101
+ ),
1102
+ }),
1103
+ );
1104
+ yield* manager.open(openInput());
1105
+ const process = ptyAdapter.processes[0]!;
1106
+ process.emitData("a".repeat(maxBytes));
1107
+ let written = yield* Queue.take(writes);
1108
+ for (let index = 0; index < 16; index += 1) {
1109
+ process.emitData("b".repeat(1024));
1110
+ written += yield* Queue.take(writes);
1111
+ }
1112
+ expect(written).toBeLessThan(maxBytes * 2);
1113
+ const expected = "a".repeat(maxBytes - 16 * 1024) + "b".repeat(16 * 1024);
1114
+ const persisted = yield* fs.readFileString(yield* historyLogPath(logsDir));
1115
+ expect(Buffer.byteLength(persisted)).toBe(maxBytes + 16 * 1024);
1116
+ for (const failure of [undefined, "write", "rename"] as const) {
1117
+ let failed = false;
1118
+ const fail = () => {
1119
+ failed = true;
1120
+ return Effect.fail(
1121
+ PlatformError.systemError({
1122
+ _tag: "Unknown",
1123
+ module: "FileSystem",
1124
+ method: failure === "write" ? "writeFileString" : "rename",
1125
+ cause: { code: "ENOSPC" },
1126
+ }),
1127
+ );
1128
+ };
1129
+ const recovered = yield* createManager(5_000, { historyByteLimit: maxBytes }).pipe(
1130
+ Effect.provideService(FileSystem.FileSystem, {
1131
+ ...fs,
1132
+ writeFileString: (file, data, options) =>
1133
+ failure === "write" && !failed && data === expected
1134
+ ? fs.writeFileString(file, "partial", options).pipe(Effect.andThen(fail))
1135
+ : fs.writeFileString(file, data, options),
1136
+ rename: (from, to) => (failure === "rename" && !failed ? fail() : fs.rename(from, to)),
1137
+ }),
1138
+ );
1139
+ const recoveredPath = yield* historyLogPath(recovered.logsDir);
1140
+ yield* fs.makeDirectory(recovered.logsDir, { recursive: true });
1141
+ yield* fs.writeFileString(recoveredPath, persisted);
1142
+ const snapshot = yield* recovered.manager.open(openInput());
1143
+ expect(snapshot.status).toBe("running");
1144
+ expect(snapshot.history).toBe(expected);
1145
+ expect(failed).toBe(failure !== undefined);
1146
+ expect(yield* fs.readFileString(recoveredPath)).toBe(
1147
+ failure === undefined ? expected : persisted,
1148
+ );
1149
+ expect(yield* fs.readDirectory(recovered.logsDir)).toHaveLength(1);
1150
+ }
1151
+ yield* manager.close({ threadId: "thread-1" });
1152
+ expect((yield* manager.open(openInput())).history).toBe(expected);
1153
+ expect(yield* fs.readFileString(yield* historyLogPath(logsDir))).toBe(expected);
1154
+ }),
1155
+ );
1156
+
1157
+ it.effect("rewrites history after an append fails partway through", () =>
1158
+ Effect.gen(function* () {
1159
+ const fs = yield* FileSystem.FileSystem;
1160
+ const writes = yield* Queue.unbounded<void>();
1161
+ let failAppend = false;
1162
+ const { manager, ptyAdapter, logsDir } = yield* createManager().pipe(
1163
+ Effect.provideService(FileSystem.FileSystem, {
1164
+ ...fs,
1165
+ writeFileString: (path, data, options) => {
1166
+ if (options?.flag === "a" && failAppend) {
1167
+ failAppend = false;
1168
+ return fs.writeFileString(path, data.slice(0, 1), options).pipe(
1169
+ // The file cannot also be a parent directory: fail after the partial append.
1170
+ Effect.andThen(fs.writeFileString(`${path}/missing`, data)),
1171
+ Effect.ensuring(Queue.offer(writes, undefined)),
1172
+ );
1173
+ }
1174
+ return fs
1175
+ .writeFileString(path, data, options)
1176
+ .pipe(
1177
+ Effect.tap(() => (data.length > 0 ? Queue.offer(writes, undefined) : Effect.void)),
1178
+ );
1179
+ },
1180
+ }),
1181
+ );
1182
+ yield* manager.open(openInput());
1183
+ const process = ptyAdapter.processes[0]!;
1184
+ process.emitData("start:");
1185
+ yield* Queue.take(writes);
1186
+ failAppend = true;
1187
+ process.emitData("middle");
1188
+ yield* Queue.take(writes);
1189
+ expect(failAppend).toBe(false);
1190
+ process.emitData(":end");
1191
+ yield* Queue.take(writes);
1192
+ expect(yield* fs.readFileString(yield* historyLogPath(logsDir))).toBe("start:middle:end");
1193
+ yield* manager.close({ threadId: "thread-1" });
1194
+ }),
1195
+ );
1196
+
1197
it.effect("releases delivered output while the process queue stays busy", () =>
1198
Effect.gen(function* () {
1199
// Observe retained payloads, since delivery and bounded history alone cannot detect a leak.
apps/server/src/terminal/Manager.ts
+77
-12
@@ -878,6 +878,12 @@ interface TerminalHistoryChunk {
878
lineBreaks: number;
879
}
880
881
+interface TerminalHistoryPersistenceCursor {
882
+ readonly generation: number;
883
+ readonly offset: number;
884
+ readonly fileBytes: number;
885
+}
886
+
887
export class BoundedTerminalHistory {
888
private readonly maxLines: number;
889
private readonly maxBytes: number;
@@ -888,6 +894,8 @@ export class BoundedTerminalHistory {
894
// Reading the old string's tail on each append can force chunk concatenation.
895
private lastCodeUnit: number | undefined;
896
private cachedValue: string | null = "";
897
+ private generation = 0;
898
+ private appendedLength = 0;
899
900
constructor(maxLines: number, initial: string, maxBytes = DEFAULT_HISTORY_BYTE_LIMIT) {
901
this.maxLines = maxLines;
@@ -897,6 +905,7 @@ export class BoundedTerminalHistory {
905
906
append(text: string): void {
907
if (text.length === 0) return;
908
+ this.appendedLength += text.length;
909
this.cachedValue = null;
910
if (this.maxBytes <= 0 || this.maxLines <= 0) {
911
this.clear();
@@ -917,6 +926,8 @@ export class BoundedTerminalHistory {
926
firstCode <= 0xdfff
927
) {
928
// Joining a split surrogate changes its UTF-8 size from 3 to 4 bytes.
929
+ // The previous flush may have encoded the lone surrogate as a replacement character.
930
+ this.generation += 1;
931
previous.data += text[0];
932
previous.byteLength += 1;
933
this.byteLength += 1;
@@ -1035,6 +1046,8 @@ export class BoundedTerminalHistory {
1046
}
1047
1048
clear(): void {
1049
+ this.generation += 1;
1050
+ this.appendedLength = 0;
1051
this.chunks = [];
1052
this.start = 0;
1053
this.byteLength = 0;
@@ -1043,6 +1056,38 @@ export class BoundedTerminalHistory {
1056
this.cachedValue = "";
1057
}
1058
1059
+ persistenceUpdate(previous?: TerminalHistoryPersistenceCursor) {
1060
+ const offset = this.appendedLength;
1061
+ let data: string | undefined;
1062
+ if (previous?.generation === this.generation) {
1063
+ let remaining = offset - previous.offset;
1064
+ const tail: string[] = [];
1065
+ for (let index = this.chunks.length - 1; remaining > 0 && index >= this.start; index -= 1) {
1066
+ const chunk = this.chunks[index]!.data;
1067
+ const suffix = chunk.slice(Math.max(0, chunk.length - remaining));
1068
+ tail.push(suffix);
1069
+ remaining -= suffix.length;
1070
+ }
1071
+ if (remaining === 0) data = tail.toReversed().join("");
1072
+ }
1073
+ // Keep the on-disk log bounded while amortizing compaction across new output.
1074
+ // Readers already cap the plain-text tail by bytes and lines.
1075
+ const append =
1076
+ data !== undefined &&
1077
+ previous !== undefined &&
1078
+ previous.fileBytes + Buffer.byteLength(data) <= this.maxBytes * 2;
1079
+ const output = append && data !== undefined ? data : this.value();
1080
+ return {
1081
+ data: output,
1082
+ append,
1083
+ cursor: {
1084
+ generation: this.generation,
1085
+ offset,
1086
+ fileBytes: (append ? previous.fileBytes : 0) + Buffer.byteLength(output),
1087
+ },
1088
+ };
1089
+ }
1090
+
1091
value(): string {
1092
if (this.cachedValue !== null) return this.cachedValue;
1093
this.cachedValue = this.chunks
@@ -1939,6 +1984,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
1984
yield* registerKillFiber(process, fiber);
1985
});
1986
1987
+ const persistedHistory = new WeakMap<BoundedTerminalHistory, TerminalHistoryPersistenceCursor>();
1988
const persistWorker = yield* makeKeyedCoalescingWorker<
1989
string,
1990
PersistHistoryRequest,
@@ -1959,9 +2005,19 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
2005
return;
2006
}
2007
2008
+ const update = request.history.persistenceUpdate(
2009
+ request.immediate ? undefined : persistedHistory.get(request.history),
2010
+ );
2011
+ if (update.append && update.data.length === 0) return;
2012
+ // An append may partially succeed before failing. Retry from a full snapshot,
2013
+ // never from an uncertain file offset.
2014
+ persistedHistory.delete(request.history);
2015
yield* fileSystem
1963
- .writeFileString(historyPath(threadId, terminalId), request.history.value())
2016
+ .writeFileString(historyPath(threadId, terminalId), update.data, {
2017
+ flag: update.append ? "a" : "w",
2018
+ })
2019
.pipe(
2020
+ Effect.tap(() => Effect.sync(() => persistedHistory.set(request.history, update.cursor))),
2021
Effect.catch((error) =>
2022
Effect.logWarning("failed to persist terminal history", {
2023
threadId,
@@ -2052,17 +2108,15 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
2108
const history = new BoundedTerminalHistory(historyLineLimit, raw, historyByteLimit);
2109
const capped = history.value();
2110
if (migrating || truncated || capped !== raw) {
2055
- const write = migrating
2056
- ? Effect.gen(function* () {
2057
- const temporaryPath = yield* fileSystem.makeTempFileScoped({
2058
- directory: logsDir,
2059
- prefix: ".history-",
2060
- });
2061
- yield* fileSystem.writeFileString(temporaryPath, capped);
2062
- yield* fileSystem.rename(temporaryPath, nextPath);
2063
- }).pipe(Effect.scoped)
2064
- : fileSystem.writeFileString(nextPath, capped);
2065
- yield* write.pipe(
2111
+ const write = Effect.gen(function* () {
2112
+ const temporaryPath = yield* fileSystem.makeTempFileScoped({
2113
+ directory: logsDir,
2114
+ prefix: ".history-",
2115
+ });
2116
+ yield* fileSystem.writeFileString(temporaryPath, capped);
2117
+ yield* fileSystem.rename(temporaryPath, nextPath);
2118
+ }).pipe(
2119
+ Effect.scoped,
2120
Effect.mapError(
2121
(cause) =>
2122
new TerminalHistoryError({
@@ -2073,6 +2127,17 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
2127
}),
2128
),
2129
);
2130
+ yield* migrating
2131
+ ? write
2132
+ : write.pipe(
2133
+ Effect.catch((error) =>
2134
+ Effect.logWarning("failed to compact terminal history", {
2135
+ threadId,
2136
+ terminalId,
2137
+ error,
2138
+ }),
2139
+ ),
2140
+ );
2141
}
2142
if (migrating) {
2143
yield* fileSystem.remove(sourcePath, { force: true }).pipe(