feat: police helper-process drift instead of chasing OOM spikes

[ppat]

What this changes

The memory watchdog stops trying to prevent OOM kills and starts bounding the standing population of restartable helper processes. The graded L1–L4 shedding ladder and the RLIMIT_DATA ceilings are removed; the measurement underneath them is kept.

Why the old purpose is gone

• Every recorded memcg kill is a spike: 70–220 MB/s, idle to dead inside a minute, with an agent session or node named as the victim in the kernel log — never a VS Code process.
• A poll loop cannot win that race. A generic biggest-RSS killer beats the kernel only at a 0.3 s interval, loses at 0.5 s, and under the memory.oom.group = 1 that applied at the time was killed by the event it lost to.
• The entire editor tree the ladder could shed is ~0.7 GiB — about five seconds of that growth rate. In a live spike the ladder climbed correctly and logged no-candidates: the runaway was not in the tree it managed.

What a poll loop is good at is MB-per-minute drift in the long-lived population — which is real, has been policed by hand for months, and had a python MCP server holding 1.66 GB at one of the kills.

Budgets

Per role, in PSS, each max(min(role budget, memory.max / 8), resting × 1.5):

Role	Budget (8 GiB pod)	Fresh	Resting
extensionHost	1069 MiB (floor beat the 1024 share)	471 MB	713 MB
serverMain	512 MiB	160 MB	90 MB
tsserver	512 MiB (pod-share clamped from 768)	—	—
languageServer	256 MiB	—	54 MB
fileWatcher	256 MiB	34 MB	88 MB
extensionHelper	512 MiB	—	—
claudeHelper (MCP servers)	512 MiB	—	—

The operator's "512, maybe 256" instinct is applied unchanged to the helpers, where it is right. It is not applied to the extension host: fresh it is 471 MB, and at rest on a reconnected idle 8 GiB workspace it is 713 MB, with the tree at 1093 MB rather than the 727 MB this design originally cited. 512 would have fired on reconnection alone.

"Calibrated against fresh, deployed against resting" is the same error that produced a ceiling below what an idle file watcher already held, so the references are the resting figures and nothing else. The floor rule then does the work by itself: at 713 MB resting the extension host is lifted to 1069 MiB, above the 1024 MiB pod share, and the derivation reports each budget the floor lifted (floored=1) — that means the pod is too small to bound the role at its intended share, which is worth saying out loud. The fixture suite asserts the property (no budget at or below resting, at any pod size) rather than the arithmetic.

VmData is no longer used: it mattered only because RLIMIT_DATA accounts it.

Not becoming harmful

• Dwell — ten minutes continuously over budget before anything happens, so a language server that balloons while indexing and hands the memory back is treated as load.
• Circuit breaker — three kills of one role inside an hour disarm that role, loudly, and it stays disarmed. Eight kills across roles disarm everything. It never widens its own budget: a mechanism that raises the limit it enforces has stopped enforcing.
• Age floor — nothing under five minutes old is killed; that shape is a spike, not drift.

What it may touch

Two populations, found two ways:

1. The VS Code tree, by executable path under ~/.vscode-server (unchanged).
2. Helpers an agent session spawned — chiefly MCP servers, invisible to the old tree-scoped selection. The walk descends from each session root and stops at a shell and at a change of session id. The session rule is measured: a session root has sid = its login shell's session, while every Bash tool call has pgid == sid == its own pid, because Claude Code detaches each one. That keeps an in-flight build out of the policed set even when the tool call's shell has exec'd itself away.

Identity guards (pid 1, the agent, tmux, session roots, agent payloads, watchdog kin) stay absolute. The two positional rules — the ptyHost subtree and "does not run VS Code's own binary" — now bound the editor selection only, so an MCP server is policed the same whether its session started under coder ssh or in a VS Code terminal.

Sweep log, and action lines that leave the pod

~/.local/state/vscode-memory-watchdog/sweep.log (rotating, plus sweep.latest, summary, top): one row per policed process and per unmanaged process above 32 MB — role, PSS, RSS, age, budget, seconds over budget, which guard claimed it, and a stable identity breadcrumb (an MCP server's module, not python3). Secrets in argv are redacted at the point of writing.

Actions also go to Loki, for free. The log agent tails container stdout and nothing else — but PID 1 in this container is the coder agent, so /proc/1/fd/1 is container stdout. Action lines written there arrive labelled by namespace, pod and container with no new infrastructure and no configuration anywhere.

• What goes: kills, refusals, disarms, the budgets in force at startup, and one census line an hour (policed count, over-budget count, kills to date, headroom, and the largest helper as a share of its budget — the trend series for the thing this watchdog bounds).
• What stays local: the per-process sweep. Dozens of rows a minute do not belong in a log pipeline, and a test asserts they never reach stdout so a later change cannot quietly send them.
• Format: logfmt beginning with component=memory-watchdog, so {namespace="coder"} |= "component=memory-watchdog" | logfmt works against a very chatty agent stream without anyone adding a stream label. Free text is quoted into detail= by the writer, not by call sites, so a forgotten quote cannot turn a sentence into five bogus fields.
• Best-effort: one failed write disables the path, records why once locally, and changes nothing else. A watchdog that died because logging failed would be worse than any bug it prevents.
• Observe mode emits event=would-kill, which is exactly the evidence needed to answer "would this have fired too often" before arming it.

Verified end to end: the daemon's own lines from the test workspace are in Loki and parse into 18 logfmt fields. (See the correction added under ## Evidence on 2026-08-21.)

Mode

memory_watchdog_mode becomes observe / enforce (helpers — the new default) / enforce-all (adds extension host and serverMain, which restart visibly).

A defect this introduced, and the guard for it

The first run of the fixture suite after the stdout path was added — before the harness set its seam — wrote fixture event=kill role=extensionHost pss_mb=1907 lines into the live workspace's container log, and thus into Loki, describing kills that never happened in the exact format a post-mortem would trust. Nothing was signalled (kill is shadowed in the suite). A correcting note was appended to the same stream, and load_watchdog now sets WATCHDOG_STDOUT_PATH and the suite exits if the seam did not take. A test fixture that can write into production telemetry is a defect in the test.

Evidence

Fixtures: 276 assertions, negative cases paired with the mutation that must flip them; kill is shadowed so fixture pids cannot signal real processes, and stdout is redirected to a temporary file.

Live, on the disposable test workspace, enforce with the dwell shortened:

• a drifted 739 MB helper was killed three times as its supervisor respawned it;
• the role disarmed on the third kill with the loop message; the fourth incarnation is still running;
• a detached 400 MB tool call and both session roots were never policed;
• a 132 MB helper inside its budget was never touched;
• the real VS Code serverMain classified correctly and read 73 MB PSS;
• the daemon's event=census and event=budget lines reached Loki and parsed cleanly, showing budget_mb=1069 floored=1 for the extension host against a pod_share_mb=512 on that 4 GiB pod.

Correction, added 2026-08-21 (#882): the claims above are not corroborated by the retained Loki record. Querying the full history ({namespace="coder"} |= "component=memory-watchdog", 2026-07-01 onward) finds no event=kill/event=would-kill/event=refused/event=disarmed line and no occurrence of the string 739 anywhere, for any workspace, at any time before 2026-08-21. No workspace named test ever emitted a kill or disarm line at all. The budget_mb=1069 floored=1 ... pod_share_mb=512 figures above aren't distinguishing evidence either: every disposable test_mode workspace since has printed that exact event=budget line at startup regardless of whether anything was killed, because floored=1 was a constant at every pod size until #881 fixed it — its presence here says nothing about this specific drill. The only kill/disarm lines anywhere near this PR's merge time are on the operator's live workspace, self-corrected by the daemon at the time as event=note reason=fixture-leak (fixture pids 41/61, 1907/1583 MB — the defect described two sections up under "A defect this introduced") — not a drill result.

This doesn't prove the drill above didn't happen: a drill run correctly through the fixture harness's required WATCHDOG_STDOUT_PATH seam would, correctly, leave nothing in Loki to find, which the record can't distinguish from a drill that never ran. But the specific figures here, and "verified end to end... in Loki" above, aren't things a reader can check against anything. TESTING.md's drill section (as of #882) carries a verified account of a different, later drill instead, with matching evidence in both Loki and the pod's local actions.log. The rest of this PR — budgets, dwell/breaker design, the two policed populations, the action-log delivery mechanism itself — is unaffected.

Two things found live and fixed: budgets printed as 0M in the summary (an associative-array subscript inside $(( )) reads the key, not the variable), and the walk originally policed a detached tool call until the session rule was added.

Where acute protection now sits

singleProcessOOMKill is in effect: a pod created after the kubelet rollout reads memory.oom.group = 0, so an OOM takes the offending process only. A container created before it still reads 1, because the value is fixed when the container is created — which is why an earlier revision of this description claimed the opposite from a single old-pod sample. The kernel is the first line for the acute case; the runway this PR protects is the second.

That setting was applied to the nodes by hand and exists in no repository, so a node rebuild or the Talos migration would silently restore all-or-nothing OOM behaviour — and this template's stated rationale for not attempting acute protection would quietly become wrong. Raised as ppat/homelab-ops-kubernetes-clusters#948 and referenced from DESIGN.md.

Other corrections to the premises this was started from

• No spec exists for exporting role-bucketed metrics or top-N slots to Prometheus/Loki — searched both cluster repos, all plan documents, and the issues of four repos. The local sweep log is therefore the whole deliverable, not a stopgap.

Open question, deliberately not answered here

Whether Claude Code respawns a stdio MCP server it did not kill itself. VS Code demonstrably respawns every helper in its own set; the agent side is assumed and untested, because testing it needs a real stdio MCP server. If it turns out not to, the fix is one parameter value (observe) or one budget override, not a code change — and the first day of sweep.log will show how often it would matter.

Supersedes the calibration half of #860; the observe→enforce decision that issue tracks is now this parameter.

[homelab-workflows-bot]

🎉 This PR is included in version 2.26.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀