[colbymchenry]

The query pool now recycles its workers after five minutes idle, so a server that served one burst of large queries gives that memory back instead of holding it for the rest of its life. This is the worker part of #1583, split out as its own commit.

Root cause

A session grows its pool for concurrent reads, and each worker kept its graph caches, SQLite pages and heap until shutdown.

Fix (from the PR)

After a stretch with no work the pool retires every worker that has been used and starts one fresh one for the next call. A retired worker is asked to close: it closes its projects, runs a full collection and exits by itself, the path worker-teardown.ts measured as safe on Windows. One that hasn't exited after 5 seconds is terminated through the pool's start-aware path. Calls that arrive while the fresh worker starts are served in process, as before the pool's first worker is up.

What we changed

• The idle delay is five minutes, not the PR's 60 seconds, so main doesn't get slower than 1.6.2. Agents routinely pause over a minute to edit or build, and the memory still comes back when a session really goes quiet.
• The recycle also arms when a burst's last worker reports ready after the last result. Before, that pool stayed at full size until the next call.
• A warm worker that has served nothing is never recycled, so that change can't replace a clean worker over and over.
• destroy() waits for retirements underway, so a worker is not left to end with the process. perf(query): retire excess workers after idle bursts #2862 had this; the PR here did not.
• Updated the comment on ready, tests for the three changes, and the CHANGELOG bullet.

#2862 by @doomsday1906 made the same idle-worker change and is closed in favor of this one. On its own fork it measured idle RSS going from about 673 MiB to 426 MiB. The difference in design: #2862 keeps one used worker warm, and this one replaces it, so a worker's caches go too.

Validation

• Red on main: six pool tests fail, including a real worker that retires with exit code 0 and is never terminated. Each added case was also proven red by undoing its line.
• Windows 11 x64 on a busy machine: 480 child processes, each with four real workers on an excalidraw index and retiring right after a burst, all exited 0 (1,920 worker exits). The crash AGENTS.md describes did not reproduce here even with an owner terminate in place of the close (0 of 480), so this shows the path works, not that the crash can't happen. It has not run on the ARM64 VM where that crash was measured.
• excalidraw, four workers after a burst of explores: 611 MB RSS idle on main, 113 MB here.
• This is a trade-off: the first explore after five idle minutes still costs about 200 ms more (299 ms against 93 ms warm on excalidraw), and the second is back to 92 ms. An agent that stays away that long pays it once per gap.
• These numbers were measured with a short idle delay. Only the wait changed, so they hold at five minutes.
• codegraph_explore output and budgets are unchanged; workers hold no session state.
• Full suite on 2da21398, a stack of this commit and its sibling from fix: bound large-repo memory and traversal work #1583 on d494e43 (Vitest 4, CODEGRAPH_KERNEL_EXPECT=1, 4 workers): 842 files, 10,209 passed, 0 failed, 87 skipped. That suite ran with the 60-second delay. Since then this commit rebased cleanly onto cc86361, sharing no file with main's new commits besides CHANGELOG.md, and only the default delay, its comments and the CHANGELOG wording changed. On this head, query-pool and mcp-daemon pass: 54 tests, 1 skipped. No test depends on the default.

Lands #1583 (worker part) by @danusha2345.

🤖 Generated with Claude Code