The best way to control Claude Code, Codex and more from any computer or phone
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
+});