@devries-cameron20 / t3code Mirror · read-only / commits / 63426c415a
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 18:30 UTC

fix(dev): long-running dev servers no longer leak memory when other worktrees install (#35740)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Theo Browne committed Nov 12, 2026 at 17:46 UTC 63426c415af8532c08d0ac8834ee6ad23d2b34fa
6 files changed +170 -6
AGENTS.md
+2 -1
@@ -83,7 +83,8 @@ The most common defect in this repo is a change that works on the path you teste
83 - Ports derive from the worktree path and are stable across restarts, but read the real ones from the `[dev-runner]` line since occupied ports shift.
84 - Sharing over the tailnet is three steps: run `vp run dev --share` in the background, wait for the `pairingUrl:` line in its output, then give that full URL to an unpaired browser. Do not wire up `tailscale serve` by hand, open the URL yourself, or consume the user's pairing link. A browser with the reusable dev cookie can use the bare origin. If a normal one-time token was consumed, mint a fresh one with `node apps/server/src/bin.ts pair`. It carries standard scopes, while the startup URL carries admin scopes needed for Connections settings.
85 - To reuse web dev auth across worktrees, configure one fixed `T3CODE_DEV_AUTH_TOKEN` in the main checkout's gitignored `.env`. The `t3.json` setup links that file into worktrees. Never commit or publish the token or a startup URL. See [Reusable dev credential](docs/operations/development.md#reusable-dev-credential).
86 -- Stop what you started, by the PID you tracked. See rule 1.
86 +- Stop what you started, by the PID you tracked. See rule 1. `vp` does not pass SIGTERM on, so signalling the `vp run dev` PID alone leaves Vite and the server running. Stop the background task with your harness's own stop, which ends the whole tree.
87 +- Run dev servers, Metro, and builds from your own shell so they end with your session. Do not detach them with `systemd-run`, `nohup`, `setsid`, or `tmux` unless the user asks for one that outlives the session. Detached servers ran for weeks and filled RAM and swap. The dev runner stops itself above `--memory-limit-gb` (half of RAM, at most 16 GiB) on Linux.
88 - Need a second checkout? `git worktree add` it next to this worktree, not in `/tmp`. Remove it when done.
89
90 ## Test data
apps/web/vite.config.ts
+22
@@ -73,6 +73,11 @@ const builtDev = process.env.T3CODE_BUILT_DEV === "1";
73 const bundledDevEnv = process.env.T3CODE_BUNDLED_DEV?.trim().toLowerCase();
74 const bundledDev = bundledDevEnv === "1" || bundledDevEnv === "true";
75
76 +// Bundled dev and `build --watch` pass Rolldown `exclude` but not Vite's default `ignored`, so
77 +// they watch node_modules. Those files are pnpm-store hardlinks shared by every worktree, so each
78 +// `vp i` or worktree removal elsewhere rebuilds every long-running server and leaks native memory.
79 +const rolldownWatchExclude = [/[\\/]node_modules[\\/]/];
80 +
81 const buildSourcemap: boolean | "hidden" =
82 sourcemapEnv === "0" || sourcemapEnv === "false"
83 ? false
@@ -247,6 +252,20 @@ function chunkCycleGuardPlugin(): Plugin {
252 };
253 }
254
255 +// Bundled dev never evicts emitted files from memory (vitejs/vite#23781), so hashed names keep
256 +// a copy of every changed chunk from every rebuild. Fixed names overwrite the previous copy.
257 +function bundledDevStableNamesPlugin(): Plugin {
258 + return {
259 + name: "t3code:bundled-dev-stable-names",
260 + apply: "serve",
261 + outputOptions: (options) => ({
262 + ...options,
263 + chunkFileNames: "assets/[name].js",
264 + assetFileNames: "assets/[name][extname]",
265 + }),
266 + };
267 +}
268 +
269 // Stamps index.html's title with the name branding.ts resolves once the app
270 // loads, so a tab opens on the right channel instead of flashing another's.
271 // Desktop swaps in its injected branding from an inline script in index.html.
@@ -307,6 +326,7 @@ export default defineConfig(() => {
326 react({ compiler: true }),
327 tailwindPlugins(bundledDev),
328 warmBundledDevPlugin(),
329 + bundledDev ? bundledDevStableNamesPlugin() : undefined,
330 ],
331 optimizeDeps: {
332 include: [
@@ -362,6 +382,7 @@ export default defineConfig(() => {
382 warmup: {
383 clientFiles: ["./src/main.tsx"],
384 },
385 + watch: { exclude: rolldownWatchExclude },
386 ...(devProxyTarget
387 ? {
388 // Share prefixes with the backend catch-all so the proxy and 404 lists cannot drift.
@@ -397,6 +418,7 @@ export default defineConfig(() => {
418 emptyOutDir: true,
419 manifest: true,
420 sourcemap: buildSourcemap,
421 + ...(builtDev ? { watch: { exclude: rolldownWatchExclude } } : {}),
422 rolldownOptions: {
423 output: {
424 // PDF.js resolves decoder modules and ICC data relative to wasmUrl.
docs/operations/development.md
+4 -1
@@ -124,7 +124,7 @@ Leave `VITE_HTTP_URL` and `VITE_WS_URL` unset. Vite proxies the backend through
124 origin so the same build works over localhost and remote connections.
125
126 Shared runs enable bundled dev to avoid a network round trip for each import level.
127 -`T3CODE_BUNDLED_DEV=0` opts out when debugging bundler differences. Two reload traps matter
127 +`T3CODE_BUNDLED_DEV=0` opts out when debugging bundler differences. These traps matter
128 when changing this setup:
129
130 - The web entry must dynamically import the app so React refresh initializes before application
@@ -134,6 +134,9 @@ when changing this setup:
134 - The app and its routes are lazy chunks, built on first request. A plugin pre-bundles the
135 startup chain when the server starts. Renaming or moving a startup route or the app entry
136 silently drops it from that list.
137 +- Bundled dev and `--built` hand Rolldown its own watcher, which skips Vite's default
138 + `node_modules` ignore. Those files are pnpm-store hardlinks, so another worktree's install or
139 + removal rebuilds every long-running server and leaks memory. Keep `node_modules` excluded.
140
141 The workarounds live in the [web entry](../../apps/web/src/bootstrap.ts),
142 [Tailwind plugin](../../apps/web/vite/tailwind.ts), and
scripts/dev-runner.ts
+24 -4
@@ -20,6 +20,7 @@ import * as Schema from "effect/Schema";
20 import { Argument, Command, Flag } from "effect/cli";
21 import { ChildProcess } from "effect/process";
22
23 +import { defaultDevMemoryLimitBytes, enforceDevMemoryLimit } from "./lib/dev-memory-limit.ts";
24 import { type DevShareError, shareDevServer, unshareDevServer } from "./lib/dev-share.ts";
25 import { loadRepoEnv } from "./lib/public-config.ts";
26
@@ -690,6 +691,7 @@ interface DevRunnerCliInput {
691 readonly share: boolean;
692 readonly seed?: boolean | undefined;
693 readonly built: boolean;
694 + readonly memoryLimitGb?: number | undefined;
695 readonly runArgs: ReadonlyArray<string>;
696 }
697
@@ -885,10 +887,9 @@ export const runDevRunnerWithInput = Effect.fn("dev-runner.runDevRunnerWithInput
887 env,
888 extendEnv: false,
889 shell: spawnCommand.shell,
888 - // Keep Vite+ in the same process group so terminal signals (Ctrl+C)
889 - // reach it directly. Effect defaults to detached: true on non-Windows,
890 - // which would put the runner in a new group and require manual forwarding.
891 - detached: false,
890 + // Its own process group: teardown signals the whole group, because vp
891 + // does not pass SIGTERM on to Vite and the server.
892 + detached: true,
893 forceKillAfter: "1500 millis",
894 }).pipe(
895 Effect.mapError(
@@ -901,6 +902,10 @@ export const runDevRunnerWithInput = Effect.fn("dev-runner.runDevRunnerWithInput
902 ),
903 );
904
905 + const memoryLimitBytes =
906 + input.memoryLimitGb === undefined
907 + ? defaultDevMemoryLimitBytes()
908 + : input.memoryLimitGb * 1024 ** 3;
909 const exitCode = yield* child.exitCode.pipe(
910 Effect.mapError(
911 (cause) =>
@@ -910,6 +915,7 @@ export const runDevRunnerWithInput = Effect.fn("dev-runner.runDevRunnerWithInput
915 cause,
916 }),
917 ),
918 + Effect.raceFirst(enforceDevMemoryLimit(memoryLimitBytes)),
919 );
920 if (exitCode !== 0) {
921 return yield* new DevRunnerProcessExitError({
@@ -919,6 +925,8 @@ export const runDevRunnerWithInput = Effect.fn("dev-runner.runDevRunnerWithInput
925 }
926 });
927
928 +const NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
929 +
930 const devRunnerCli = Command.make("dev-runner", {
931 mode: Argument.Literals("mode", DEV_RUNNER_MODES).pipe(
932 Argument.withDescription("Development mode to run."),
@@ -984,6 +992,18 @@ const devRunnerCli = Command.make("dev-runner", {
992 ),
993 Flag.withDefault(false),
994 ),
995 + memoryLimitGb: Flag.Int("memory-limit-gb").pipe(
996 + Flag.withSchema(NonNegativeInt),
997 + Flag.withDescription(
998 + "Stop the dev server when it and its child processes use more than this many GiB of RAM plus swap (equivalent to T3CODE_DEV_MEMORY_LIMIT_GB). Defaults to half of RAM, at most 16. 0 turns it off. Linux only.",
999 + ),
1000 + Flag.withFallbackConfig(
1001 + Config.schema(NonNegativeInt, "T3CODE_DEV_MEMORY_LIMIT_GB").pipe(
1002 + Config.option,
1003 + Config.map(Option.getOrUndefined),
1004 + ),
1005 + ),
1006 + ),
1007 runArgs: Argument.String("run-arg").pipe(
1008 Argument.withDescription("Additional Vite+ run args (pass after `--`)."),
1009 Argument.variadic(),
scripts/lib/dev-memory-limit.test.ts new
+23
@@ -0,0 +1,23 @@
1 +import { assert, it } from "@effect/vitest";
2 +
3 +import {
4 + parseProcStatParentPid,
5 + parseProcStatusBytes,
6 + processTreePids,
7 +} from "./dev-memory-limit.ts";
8 +
9 +it("counts RAM and swap for the dev runner's descendants only", () => {
10 + assert.strictEqual(parseProcStatParentPid("812 (node (vite) 2) S 77 812 812 0 -1"), 77);
11 + assert.strictEqual(
12 + parseProcStatusBytes("Name:\tnode\nVmRSS:\t 2048 kB\nVmSwap:\t 1024 kB\nThreads:\t9\n"),
13 + 3 * 1024 * 1024,
14 + );
15 + // Listed before its parent, as /proc may order them.
16 + const processes = [
17 + { pid: 30, ppid: 20 },
18 + { pid: 20, ppid: 10 },
19 + { pid: 11, ppid: 1 },
20 + { pid: 10, ppid: 1 },
21 + ];
22 + assert.deepStrictEqual([...processTreePids(10, processes)].sort(), [10, 20, 30]);
23 +});
scripts/lib/dev-memory-limit.ts new
+95
@@ -0,0 +1,95 @@
1 +/** Stops a dev server whose process tree outgrows a memory limit, so a leak cannot fill RAM and swap. */
2 +
3 +import * as NodeOS from "node:os";
4 +
5 +import * as HostProcess from "@t3tools/shared/HostProcess";
6 +import * as Effect from "effect/Effect";
7 +import * as FileSystem from "effect/FileSystem";
8 +import * as Schema from "effect/Schema";
9 +
10 +const GiB = 1024 ** 3;
11 +
12 +/** Half of RAM, at most 16 GiB. A fresh bundled-dev server uses about 7 GiB. */
13 +export const defaultDevMemoryLimitBytes = (totalBytes = NodeOS.totalmem()) =>
14 + Math.min(16 * GiB, Math.floor(totalBytes / 2));
15 +
16 +export class DevRunnerMemoryLimitError extends Schema.TaggedError<DevRunnerMemoryLimitError>()(
17 + "DevRunnerMemoryLimitError",
18 + { usedBytes: Schema.Number, limitBytes: Schema.Number },
19 +) {
20 + override get message(): string {
21 + const gib = (bytes: number) => (bytes / GiB).toFixed(1);
22 + return `The dev server used ${gib(this.usedBytes)} GiB of RAM and swap, over its ${gib(this.limitBytes)} GiB limit, so it was stopped. Start it again, or set --memory-limit-gb (T3CODE_DEV_MEMORY_LIMIT_GB; 0 turns the limit off).`;
23 + }
24 +}
25 +
26 +export interface ProcessSample {
27 + readonly pid: number;
28 + readonly ppid: number;
29 +}
30 +
31 +/** `comm` can hold spaces and parentheses, so fields are read after its last `)`. */
32 +export function parseProcStatParentPid(stat: string): number | undefined {
33 + const ppid = Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[1]);
34 + return Number.isInteger(ppid) ? ppid : undefined;
35 +}
36 +
37 +export function parseProcStatusBytes(status: string): number {
38 + const kib = (field: string) =>
39 + Number(new RegExp(`^${field}:\\s+(\\d+) kB`, "m").exec(status)?.[1] ?? 0);
40 + return (kib("VmRSS") + kib("VmSwap")) * 1024;
41 +}
42 +
43 +export function processTreePids(rootPid: number, processes: ReadonlyArray<ProcessSample>) {
44 + const tree = new Set([rootPid]);
45 + for (let grew = true; grew;) {
46 + grew = false;
47 + for (const { pid, ppid } of processes) {
48 + if (tree.has(ppid) && !tree.has(pid)) {
49 + tree.add(pid);
50 + grew = true;
51 + }
52 + }
53 + }
54 + return tree;
55 +}
56 +
57 +const readProcessTreeBytes = Effect.fn("DevRunner.readProcessTreeBytes")(function* (
58 + rootPid: number,
59 +) {
60 + const fs = yield* FileSystem.FileSystem;
61 + // Processes exit between listing and reading, so each read may fail.
62 + const read = (path: string) => fs.readFileString(path).pipe(Effect.option);
63 + const entries = yield* fs.readDirectory("/proc").pipe(Effect.orElseSucceed(() => []));
64 + const pids = entries.filter((entry) => /^\d+$/.test(entry));
65 + const processes: ProcessSample[] = [];
66 + for (const pid of pids) {
67 + const stat = yield* read(`/proc/${pid}/stat`);
68 + const ppid = stat._tag === "Some" ? parseProcStatParentPid(stat.value) : undefined;
69 + if (ppid !== undefined) processes.push({ pid: Number(pid), ppid });
70 + }
71 + let bytes = 0;
72 + for (const pid of processTreePids(rootPid, processes)) {
73 + const status = yield* read(`/proc/${pid}/status`);
74 + if (status._tag === "Some") bytes += parseProcStatusBytes(status.value);
75 + }
76 + return bytes;
77 +});
78 +
79 +/**
80 + * Samples this process and its descendants every 30 seconds and fails once
81 + * they hold more than `limitBytes` of RAM plus swap. Linux only; elsewhere it
82 + * never completes.
83 + */
84 +export const enforceDevMemoryLimit = Effect.fn("DevRunner.enforceDevMemoryLimit")(function* (
85 + limitBytes: number,
86 +) {
87 + if ((yield* HostProcess.Platform) !== "linux" || limitBytes <= 0) return yield* Effect.never;
88 + while (true) {
89 + yield* Effect.sleep("30 seconds");
90 + const usedBytes = yield* readProcessTreeBytes(process.pid);
91 + if (usedBytes > limitBytes) {
92 + return yield* new DevRunnerMemoryLimitError({ usedBytes, limitBytes });
93 + }
94 + }
95 +});