[colbymchenry]

Summary

#3126 (unreleased) ends every query worker after five minutes idle, so a burst's memory comes back. That fixed #3027, but it also made the first call after a pause slower than 1.6.2. REG measured 634 to 729 ms on django against 565 to 587.

The pool now keeps the worker that served last and shrinks it in place, instead of ending it and starting a clean one. The first call after idle is now about as fast as any other, and the burst's memory still comes back. It costs about 70 MB more than main when idle, on any index.

First call after 5 real idle minutes (ms, 3 gaps)	1.6.2	main	this PR	warm on this PR
flask	111 / 79 / 82	180 / 172 / 166	43 / 41 / 43	41
django	886 / 676 / 443	744 / 878 / 660	170 / 171 / 200	214
elasticsearch	956 / 641 / 674	2752 / 2561 / 1419	764 / 234 / 243	256

Root cause

The 500 ms isn't worker startup: the replacement worker is already ready when the call arrives. It isn't compiled code either: reopening the project inside a warm isolate still costs 460 to 660 ms. Giving the worker a compile cache, as the indexing workers have, moved ready by under 40 ms and the first call not at all.

It is what a connection works out once and remembers. Profile of the first call on django:

Part	ms	Per
Dominant file, a scan of every edge	212 to 234	connection
Name indexes	about 85	connection
git probe for a nested repo	about 30	handler
tree-sitter's first parse	about 50	worker

These can't be handed to a clean worker, because the change stamp they're checked against only means something on the connection that took it.

A call landing as the recycle ran was worse than the gap numbers suggest. With no warm worker it ran on the main thread, cold: 884 to 1,154 ms just after the deadline, the next call just as slow, and the transport held for up to 417 ms in one case.

Fix

• The pool retires the workers a burst added, as before, and keeps the one that served last.
• The kept worker closes every project but the last one used, and its connections give up their page cache and file mapping. The next reads fill them again.
• Compiled code, the remembered answers and tree-sitter all stay. No worker stops, so ready never drops and a call during the trim just waits a few milliseconds.
• A worker still holding over 256 MB after its trim is replaced as on main, so keeping one can't keep hold of what a large query left behind. A trimmed worker holds about 80 MB, so this hasn't fired on any repo here. In that rare path a call during the replacement's start still runs in process, as it does on main.

The options

On django, one worker, each measured the same way:

Option	Working set / private MB	First call
Clean worker (main)	106 / 79	732 ms
Clean worker primed with the dominant file and git probe	144 / 80	410 ms
...plus the substring index	182 / 148	335 ms
...plus every remembered answer	213 / 153	319 ms
Clean worker replaying the last query	295 / 258	189 ms
Kept worker, trimmed (this PR)	168 / 175	152 ms

Priming only gets part of the way, and a replay ends up holding as much as a kept worker with a worker restart on top. Keeping one is also simpler: it removes the replacement's start from the normal path.

What the trim contains, and why. Each step was tested alone on elasticsearch, side by side through the same real gaps:

Arm	First call (3 gaps)	Idle ws / private
1.6.2	986 / 661 / 908	393 / 294
No trim	210 / 172 / 167	429 / 325
File mapping only	200 / 254 / 185	274 / 317
Page cache only	641 / 208 / 211	353 / 246
Both (this PR)	654 / 222 / 222	205 / 250

• The mapping step costs nothing measurable and gives back about 155 MB of working set.
• The page cache step gives back about 80 MB of private memory, which is the 64 MB per connection The query worker pool grows on a burst and never shrinks; each worker opens every project #3027 names. Its cost appears on the first gap only, in the arms that release it, which fits those pages being read back once. I didn't observe the disk reads directly. It stays under 1.6.2 in the paired run, so I kept it. Dropping it would give an even first call on large indexes for about 70 MB more when idle, if you'd rather have that.
• There's deliberately no forced garbage collection. I started with a last-resort one, then found V8 shrinks an idle thread's heap by itself well before five minutes. It added 3 MB at that point, so it came out and worker-teardown.ts is untouched.

Validation

All on Windows, through the real MCP server, under 1.6.2's node.exe and flags with REG's method.

Memory after a burst of four workers and five idle minutes (working set / private MB):

Repo	Peak	1.6.2 idle	main idle	this PR idle	First call: main → this PR
excalidraw	812 / 832	505 / 482	177 / 221	244 / 295	382 → 167 ms
django	1093 / 902	695 / 486	179 / 223	247 / 295	804 → 193 ms
elasticsearch	2266 / 1756	not run	221 / 265	298 / 348	2922 → 1771 ms

The elasticsearch row is one sample on a busy machine (main's second call there took 1,532 ms). The three-gap table above is the better read.

Worst case: a call at the deadline, django: 142 to 226 ms at every offset from -300 ms to +3 s, the next call warm, the transport never held over 19 ms.

Stability:

• 240 processes, each with four real workers, shut down after, during and right behind a trim: all exited 0. That's 960 worker exits with no crash, though this box has never reproduced that crash, so it shows the path works rather than that the crash can't happen.
• 30 busy-then-quiet cycles, 600 mixed calls: no errors, and idle memory goes up and down without creeping.
• The real shared daemon behaves the same: 155 ms at the deadline.
• __tests__/query-pool.test.ts 5 times on this commit: 43 passed each time.

Tests:

• Red on main: 13 new tests fail, none of them timing-dependent: they count worker starts and follow which worker answers.
• 12 mutations undoing each new line are all caught.
• fix(mcp): idle query workers are recycled, so a burst's memory is given back #3126's six recycle tests still run, because the fake worker now reports itself too heavy to keep by default, so they exercise the replacement path. The test bodies are unchanged, apart from one option on the real-worker one.

Full suite through the gate, with the kernel, daemon enabled, 4 workers: 854 files, 10,565 passed, 0 failed, 87 skipped, 2 expected failures. No reruns.

Not covered

• macOS and Linux. PRAGMA mmap_size and shrink_memory are plain SQLite, but none of these numbers were taken there.
• Sessions longer than the 30 cycles above. The 256 MB check is the backstop.

Refs #3027. Follows #3126.

🤖 Generated with Claude Code