@devries-cameron20 / t3code-1 / commits / d1cac663a7
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

fix(server): an idle terminal no longer scans the process table every second (#21242)

Co-authored-by: Julius Marminge <julius0216@outlook.com>

tiliakoos committed Oct 20, 2026 at 01:08 UTC d1cac663a783912f69b26236777214057b569f39
2 files changed +218 -48
apps/server/src/terminal/Manager.test.ts
+138 -36
@@ -302,6 +302,9 @@ interface CreateManagerOptions {
302 >;
303 subprocessPollIntervalMs?: number;
304 processKillGraceMs?: number;
305 + registerTerminalProcesses?: Parameters<
306 + typeof TerminalManager.makeWithOptions
307 + >[0]["registerTerminalProcesses"];
308 maxRetainedInactiveSessions?: number;
309 historyByteLimit?: number;
310 ptyAdapter?: FakePtyAdapter;
@@ -352,6 +355,9 @@ const createManager = (
355 ? { subprocessPollIntervalMs: options.subprocessPollIntervalMs }
356 : {}),
357 processKillGraceMs: options.processKillGraceMs ?? 1,
358 + ...(options.registerTerminalProcesses !== undefined
359 + ? { registerTerminalProcesses: options.registerTerminalProcesses }
360 + : {}),
361 ...(options.maxRetainedInactiveSessions !== undefined
362 ? { maxRetainedInactiveSessions: options.maxRetainedInactiveSessions }
363 : {}),
@@ -1225,47 +1231,143 @@ it.layer(
1231 }),
1232 );
1233
1228 - it.effect("emits subprocess activity events when child-process state changes", () =>
1234 + it.effect("skips snapshots only when every terminal is quiet and wakes on input or output", () =>
1235 Effect.gen(function* () {
1230 - let inspect: {
1231 - readonly hasRunningSubprocess: boolean;
1232 - readonly childCommand: string | null;
1233 - readonly processIds: ReadonlyArray<number>;
1234 - } = { hasRunningSubprocess: false, childCommand: null, processIds: [] };
1235 - const { manager, getEvents } = yield* createManager(5, {
1236 - subprocessInspector: () => Effect.succeed(inspect),
1237 - subprocessPollIntervalMs: 20,
1238 - });
1239 -
1236 + let snapshots = 0;
1237 + let processes: Array<{ pid: number; ppid: number; name: string }> = [];
1238 + let duringSnapshot: Effect.Effect<void> = Effect.void;
1239 + const { manager, ptyAdapter, getEvents } = yield* createManager(5, {
1240 + processKillGraceMs: 0,
1241 + subprocessPollIntervalMs: 1_000,
1242 + processTable: Effect.gen(function* () {
1243 + snapshots += 1;
1244 + const snapshot = processes;
1245 + yield* duringSnapshot;
1246 + return snapshot;
1247 + }),
1248 + }).pipe(Effect.provide(layerWithHostPlatform("linux")));
1249 + const activity = yield* Queue.unbounded<Extract<TerminalEvent, { type: "activity" }>>();
1250 + const output = yield* Deferred.make<void>();
1251 + const unsubscribe = yield* manager.subscribe((event) =>
1252 + event.type === "activity"
1253 + ? Queue.offer(activity, event).pipe(Effect.asVoid)
1254 + : event.type === "output"
1255 + ? Deferred.succeed(output, undefined).pipe(Effect.asVoid)
1256 + : Effect.void,
1257 + );
1258 + yield* Effect.addFinalizer(() => Effect.sync(unsubscribe));
1259 yield* manager.open(openInput());
1241 - expect((yield* getEvents).some((event) => event.type === "activity")).toBe(false);
1260 + yield* manager.open(openInput({ terminalId: "second" }));
1261 + const [first, second] = ptyAdapter.processes;
1262 + const shells = ptyAdapter.processes.map(({ pid }) => ({ pid, ppid: 1, name: "zsh" }));
1263 + processes = shells;
1264 +
1265 + yield* TestClock.adjust("1 second");
1266 + assert.equal(snapshots, 1);
1267 + yield* TestClock.adjust("1 second");
1268 + assert.equal(snapshots, 2);
1269 + yield* TestClock.adjust("3 seconds");
1270 + assert.equal(snapshots, 2);
1271 + expect((yield* getEvents).filter((event) => event.type === "activity")).toEqual([]);
1272 +
1273 + processes = [...shells, { pid: 100, ppid: second!.pid, name: "vim" }];
1274 + yield* manager.write({ threadId: "thread-1", terminalId: "second", data: "vim\r" });
1275 + yield* TestClock.adjust("1 second");
1276 + expect(yield* Queue.take(activity)).toMatchObject({
1277 + terminalId: "second",
1278 + hasRunningSubprocess: true,
1279 + label: "vim",
1280 + });
1281 + yield* TestClock.adjust("2 seconds");
1282 + assert.equal(snapshots, 5);
1283 +
1284 + processes = shells;
1285 + yield* TestClock.adjust("1 second");
1286 + expect(yield* Queue.take(activity)).toMatchObject({
1287 + terminalId: "second",
1288 + hasRunningSubprocess: false,
1289 + label: "second",
1290 + });
1291 + yield* TestClock.adjust("3 seconds");
1292 + assert.equal(snapshots, 7);
1293 +
1294 + processes = [...shells, { pid: 101, ppid: first!.pid, name: "node" }];
1295 + first!.emitData("server started\r\n");
1296 + yield* Deferred.await(output);
1297 + yield* TestClock.adjust("1 second");
1298 + expect(yield* Queue.take(activity)).toMatchObject({
1299 + terminalId: DEFAULT_TERMINAL_ID,
1300 + hasRunningSubprocess: true,
1301 + label: "node",
1302 + });
1303 + assert.equal(snapshots, 8);
1304
1243 - inspect = { hasRunningSubprocess: true, childCommand: "vim", processIds: [100, 101] };
1244 - yield* waitFor(
1245 - Effect.map(getEvents, (events) =>
1246 - events.some(
1247 - (event) =>
1248 - event.type === "activity" &&
1249 - event.hasRunningSubprocess === true &&
1250 - event.label === "vim",
1251 - ),
1252 - ),
1253 - "1200 millis",
1254 - );
1305 + processes = shells;
1306 + duringSnapshot = Effect.gen(function* () {
1307 + duringSnapshot = Effect.void;
1308 + yield* manager.write({
1309 + threadId: "thread-1",
1310 + terminalId: DEFAULT_TERMINAL_ID,
1311 + data: "next command\r",
1312 + });
1313 + }).pipe(Effect.orDie);
1314 + yield* TestClock.adjust("1 second");
1315 + expect(yield* Queue.take(activity)).toMatchObject({ hasRunningSubprocess: false });
1316 + // Input during inspection still needs two subsequent unchanged snapshots.
1317 + yield* TestClock.adjust("2 seconds");
1318 + assert.equal(snapshots, 11);
1319 + yield* TestClock.adjust("3 seconds");
1320 + assert.equal(snapshots, 11);
1321 + }).pipe(Effect.provide(TestClock.layer())),
1322 + );
1323
1256 - inspect = { hasRunningSubprocess: false, childCommand: null, processIds: [] };
1257 - yield* waitFor(
1258 - Effect.map(getEvents, (events) =>
1259 - events.some(
1260 - (event) =>
1261 - event.type === "activity" &&
1262 - event.hasRunningSubprocess === false &&
1263 - event.label === "Terminal 1",
1264 - ),
1265 - ),
1266 - "1200 millis",
1324 + it.effect("discovers and registers a silent child within 30 quiet ticks", () =>
1325 + Effect.gen(function* () {
1326 + let snapshots = 0;
1327 + let processes: Array<{ pid: number; ppid: number; name: string }> = [];
1328 + const registered = yield* Deferred.make<{
1329 + readonly threadId: string;
1330 + readonly terminalId: string;
1331 + readonly processIds: ReadonlyArray<number>;
1332 + }>();
1333 + const { manager, ptyAdapter } = yield* createManager(5, {
1334 + processKillGraceMs: 0,
1335 + subprocessPollIntervalMs: 1_000,
1336 + processTable: Effect.sync(() => {
1337 + snapshots += 1;
1338 + return processes;
1339 + }),
1340 + registerTerminalProcesses: (input) =>
1341 + input.processIds.includes(100)
1342 + ? Deferred.succeed(registered, input).pipe(Effect.asVoid)
1343 + : Effect.void,
1344 + }).pipe(Effect.provide(layerWithHostPlatform("linux")));
1345 + const activity = yield* Queue.unbounded<Extract<TerminalEvent, { type: "activity" }>>();
1346 + const unsubscribe = yield* manager.subscribe((event) =>
1347 + event.type === "activity" ? Queue.offer(activity, event).pipe(Effect.asVoid) : Effect.void,
1348 );
1268 - }),
1349 + yield* Effect.addFinalizer(() => Effect.sync(unsubscribe));
1350 + yield* manager.open(openInput());
1351 + const shell = ptyAdapter.processes[0]!;
1352 + processes = [{ pid: shell.pid, ppid: 1, name: "zsh" }];
1353 + yield* TestClock.adjust("2 seconds");
1354 + assert.equal(snapshots, 2);
1355 +
1356 + processes = [...processes, { pid: 100, ppid: shell.pid, name: "node" }];
1357 + yield* TestClock.adjust("30 seconds");
1358 + assert.equal(snapshots, 3);
1359 + assert.isTrue(yield* Deferred.isDone(registered));
1360 + expect(yield* Deferred.await(registered)).toEqual({
1361 + threadId: "thread-1",
1362 + terminalId: DEFAULT_TERMINAL_ID,
1363 + processIds: [shell.pid, 100],
1364 + });
1365 + expect(yield* Queue.take(activity)).toMatchObject({
1366 + terminalId: DEFAULT_TERMINAL_ID,
1367 + hasRunningSubprocess: true,
1368 + label: "node",
1369 + });
1370 + }).pipe(Effect.provide(TestClock.layer())),
1371 );
1372
1373 it.effect("does not invoke subprocess polling until a terminal session is running", () =>
apps/server/src/terminal/Manager.ts
+80 -12
@@ -98,6 +98,8 @@ const MAX_HISTORY_CHUNK_LENGTH = 16 * 1024;
98 const DEFAULT_PERSIST_DEBOUNCE_MS = 250;
99 const DEFAULT_SUBPROCESS_POLL_INTERVAL_MS = 1_000;
100 const MAX_SUBPROCESS_POLL_INTERVAL_MS = 60_000;
101 +// Discover children started without terminal input or output.
102 +const QUIET_SUBPROCESS_SNAPSHOT_EVERY_TICKS = 30;
103 const DEFAULT_PROCESS_KILL_GRACE_MS = 1_000;
104 const DEFAULT_MAX_RETAINED_INACTIVE_SESSIONS = 128;
105 const DEFAULT_OPEN_COLS = 120;
@@ -438,6 +440,16 @@ function advanceEventSequence(session: TerminalSessionState): {
440 return { updatedAt, sequence: session.eventSequence };
441 }
442
443 +function terminalActivityMark(session: TerminalSessionState): number {
444 + return session.eventSequence + session.inputCount;
445 +}
446 +
447 +interface QuietTerminalSession {
448 + readonly process: PtyAdapter.PtyProcess | null;
449 + readonly mark: number;
450 + readonly idleSnapshots: number;
451 +}
452 +
453 function cleanupProcessHandles(session: TerminalSessionState): void {
454 session.unsubscribeData?.();
455 session.unsubscribeData = null;
@@ -2485,16 +2497,46 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
2497 }
2498 });
2499
2500 + // Two unchanged snapshots cover children forked just after the first snapshot.
2501 + // Process identity prevents a restarted shell from inheriting quiet state.
2502 + let quietSessions = new WeakMap<TerminalSessionState, QuietTerminalSession>();
2503 + let skippedQuietTicks = 0;
2504 + const isQuiet = (session: TerminalSessionState & { pid: number }) => {
2505 + const quiet = quietSessions.get(session);
2506 + return (
2507 + quiet !== undefined &&
2508 + quiet.idleSnapshots === 2 &&
2509 + quiet.process === session.process &&
2510 + quiet.mark === terminalActivityMark(session) &&
2511 + !session.hasRunningSubprocess
2512 + );
2513 + };
2514 +
2515 const pollSubprocessActivity = Effect.fn("terminal.pollSubprocessActivity")(function* () {
2516 const state = yield* readManagerState;
2490 - const runningSessions = [...state.sessions.values()].filter(
2491 - (session): session is TerminalSessionState & { pid: number } =>
2492 - session.status === "running" && Number.isInteger(session.pid),
2493 - );
2517 + const runningSessions = [...state.sessions.values()]
2518 + .filter(
2519 + (session): session is TerminalSessionState & { pid: number } =>
2520 + session.status === "running" && Number.isInteger(session.pid),
2521 + )
2522 + .map((session) => ({
2523 + session,
2524 + terminalPid: session.pid,
2525 + process: session.process,
2526 + mark: terminalActivityMark(session),
2527 + }));
2528
2529 if (runningSessions.length === 0) {
2530 return true;
2531 }
2532 + if (
2533 + runningSessions.every(({ session }) => isQuiet(session)) &&
2534 + skippedQuietTicks < QUIET_SUBPROCESS_SNAPSHOT_EVERY_TICKS - 1
2535 + ) {
2536 + skippedQuietTicks += 1;
2537 + return true;
2538 + }
2539 + skippedQuietTicks = 0;
2540
2541 const inspectorOption = yield* acquireSubprocessInspector.pipe(
2542 Effect.asSome,
@@ -2513,15 +2555,18 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
2555 );
2556
2557 if (Option.isNone(inspectorOption)) {
2558 + quietSessions = new WeakMap();
2559 return false;
2560 }
2561
2562 const { inspector: subprocessInspector, snapshotSucceeded } = inspectorOption.value;
2520 -
2563 const checkSubprocessActivity = Effect.fn("terminal.checkSubprocessActivity")(function* (
2522 - session: TerminalSessionState & { pid: number },
2564 + candidate: (typeof runningSessions)[number],
2565 ) {
2524 - const terminalPid = session.pid;
2566 + const { session, terminalPid, process } = candidate;
2567 + let mark = candidate.mark;
2568 + const previous = quietSessions.get(session);
2569 + quietSessions.delete(session);
2570 const inspectResult = yield* subprocessInspector(terminalPid).pipe(
2571 Effect.asSome,
2572 Effect.catch((reason) =>
@@ -2534,7 +2579,12 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
2579 ),
2580 );
2581
2537 - if (Option.isNone(inspectResult)) {
2582 + if (
2583 + Option.isNone(inspectResult) ||
2584 + session.status !== "running" ||
2585 + session.pid !== terminalPid ||
2586 + session.process !== process
2587 + ) {
2588 return;
2589 }
2590
@@ -2551,8 +2601,10 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
2601 );
2602 if (
2603 Option.isNone(liveSession) ||
2604 + liveSession.value !== session ||
2605 liveSession.value.status !== "running" ||
2606 liveSession.value.pid !== terminalPid ||
2607 + liveSession.value.process !== process ||
2608 (liveSession.value.hasRunningSubprocess === next.hasRunningSubprocess &&
2609 liveSession.value.childCommandLabel === nextChildLabel)
2610 ) {
@@ -2562,6 +2614,8 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
2614 liveSession.value.hasRunningSubprocess = next.hasRunningSubprocess;
2615 liveSession.value.childCommandLabel = nextChildLabel;
2616 const eventStamp = advanceEventSequence(liveSession.value);
2617 + // Only this poll's own event may advance the mark without waking it.
2618 + mark += 1;
2619
2620 return [
2621 Option.some({
@@ -2579,12 +2633,28 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
2633 if (Option.isSome(event)) {
2634 yield* publishEvent(event.value);
2635 }
2636 +
2637 + if (
2638 + snapshotSucceeded &&
2639 + !next.hasRunningSubprocess &&
2640 + session.status === "running" &&
2641 + session.pid === terminalPid &&
2642 + session.process === process &&
2643 + terminalActivityMark(session) === mark
2644 + ) {
2645 + quietSessions.set(session, {
2646 + process,
2647 + mark,
2648 + idleSnapshots: previous?.process === process && previous.mark === mark ? 2 : 1,
2649 + });
2650 + }
2651 });
2652
2653 yield* Effect.forEach(runningSessions, checkSubprocessActivity, {
2654 concurrency: "unbounded",
2655 discard: true,
2656 });
2657 +
2658 return snapshotSucceeded;
2659 });
2660
@@ -3267,10 +3337,8 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
3337 (input.terminalId === undefined || session.terminalId === input.terminalId),
3338 );
3339 if (running.length === 0) return;
3270 - const activityMark = (session: TerminalSessionState) =>
3271 - session.eventSequence + session.inputCount;
3340 const marks = new Map(
3273 - running.map((session) => [session.terminalId, activityMark(session)]),
3341 + running.map((session) => [session.terminalId, terminalActivityMark(session)]),
3342 );
3343 // Inspect now instead of trusting the last poll, so a command started
3344 // since then keeps its terminal.
@@ -3281,7 +3349,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
3349 inspector(session.pid).pipe(
3350 Effect.flatMap((result) =>
3351 result.hasRunningSubprocess ||
3284 - activityMark(session) !== marks.get(session.terminalId)
3352 + terminalActivityMark(session) !== marks.get(session.terminalId)
3353 ? Effect.void
3354 : closeSession(input.threadId, session.terminalId, false),
3355 ),