@devries-cameron20 / t3code-1 / commits / 65716ba1d7
Fork 0

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(