repair(mem): reconstruct memory runtime policy and diagnostics

[Skywind5487]

Merge unit: repair:memory-runtime (#110)

Composes two internal work line PRs into one coherent memory-runtime repair.

Composition

Work line	Internal PR	Base	Commits
line:memory-trim-policy	#131	base/memory-runtime-110 (upstream parent 3b9a963b8)	research preflight + RSS low-water + GC cooldown
line:memory-trim-diagnostics	#132	fork/memory-trim-policy (stacked on #131)	GC/trim timing split + fragmentation + VmSwap

Each internal line exposes only its intent delta against the current-upstream
parent, so review surfaces stay minimal. This integration PR lands both lines
as one merge unit into main.

---

Summary

Repairs the Phase-2 repair:memory-runtime merge unit from #110 on top of refreshed upstream main (3b9a963b8e5cdb804a422755bed9a60fcd778273).

This is a conscious port of the Phase-1 memory-runtime contracts onto the current merged allocator-trim seam, not a replay of the historical fork branch shape. The policy line remains independently correct; diagnostics extends it and is explicitly fail-open, matching the composition decision in PR #108.

Current-upstream / prior-art classification

• Merged/current authority: feat(mem): config-driven allocator trim with telemetry (#66355 salvage) NousResearch/hermes-agent#76905 is the allocator-trim substrate used here: config-driven trim_memory(), /proc/self/status snapshots, glibc probing, lifecycle callers, normal cooldown, and the accepted forced-close floor.
• Merged/current seam confirmation: fix(catalog)+perf(compressor): api_key headers for http MCP servers; post-compression trim (#70782 split-salvage) NousResearch/hermes-agent#77356 routes post-compression recovery through that same trim_memory() seam rather than introducing a second collection path.
• Merged/adjacent: fix(gateway): bound the agent cache by memory, not just count and age (#80764, salvage of #80795) NousResearch/hermes-agent#81127 adds a gateway agent-cache memory-pressure valve and calls the same trim seam after releasing cache references. It does not implement this ticket's RSS low-water / independent GC-cooldown contract.
• Closed/unmerged rejected shape: perf: proactive GC trigger, O(1) active session count, WAL checkpoint tuning NousResearch/hermes-agent#46022 proposed proactive GC above 400 MB, but maintainer review identified its RSS source as a high-water mark that could keep retriggering full GC after one crossing. This repair instead uses current VmRSS from /proc/self/status.
• Earlier ancestry, not current authority: feat(mem): add config-driven allocator trim NousResearch/hermes-agent#63708 / feat(gateway): periodic memory trim in idle reaper for long-lived processes NousResearch/hermes-agent#64591 / feat(mem): config-driven allocator trim with telemetry and lifecycle coverage NousResearch/hermes-agent#66355 are earlier allocator-trim iterations superseded by the merged feat(mem): config-driven allocator trim with telemetry (#66355 salvage) NousResearch/hermes-agent#76905 line; they are provenance only.
• Open/unmerged, out of scope: fix(agent): collect after large tool results (#70684) NousResearch/hermes-agent#80974 proposes targeted GC after individual large tool results. It is design evidence only and is not folded into this housekeeping/runtime repair.

The durable preflight is recorded in docs/research/memory-runtime-issue-110.md with pinned refs and reconstruction decisions.

Policy behavior (from #131)

• Adds context.memory_trim.threshold_mb as a non-forced RSS low-water gate.
• Uses current VmRSS; unreadable/missing RSS fails open because telemetry absence cannot prove the process is below threshold.
• A low-water skip is only an eligibility check: it does not consume the allocator-trim cooldown or the 5-second forced-close floor.
• Adds an independent gc_cooldown_seconds (historical/default contract: 300 s). malloc_trim(0) remains eligible on the normal trim cadence while Python GC is cooling down.
• Invalid GC cooldown values fall back to 300 s rather than accidentally inheriting the allocator trim's 60 s default.
• force=True bypasses the RSS gate and GC cooldown while retaining upstream's accepted burst-close force floor.

Diagnostics behavior (from #132)

• Attributes recovery cost separately as gc_ms and trim_ms, and logs whether GC actually ran.
• Adds best-effort VmSwap evidence from /proc/self/status.
• Collects pre-recovery glibc fragmentation evidence from malloc_info(3), parsing only process-level totals so per-arena and root summaries are not double-counted.
• Replaces the historical predictable /tmp/hermes_malloc_info_<pid>.xml shape with libc tmpfile().
• Diagnostic collection is wrapped independently: parser/platform/libc/stdio failures degrade to missing diagnostics and cannot block GC or allocator trim.

Regression coverage

Policy coverage in tests/hermes_cli/test_mem_trim.py includes:

• low-water skip;
• missing-RSS fail-open behavior;
• low-water skips not suppressing a following forced trim;
• independent GC cooldown with allocator trim still running;
• force bypass of low-water and GC cooldown;
• valid and invalid policy config coercion;
• preservation of existing kill-switch, cooldown, forced-close floor, and libc-failure behavior.

Diagnostics coverage in tests/hermes_cli/test_mem_trim_diagnostics.py includes:

• VmSwap parsing;
• process-total fragmentation parsing without double counting;
• malformed diagnostics as best effort;
• diagnostic exceptions not blocking recovery;
• GC-vs-trim timing attribution, fragmentation, and swap in operator logs;
• explicit logging of a GC-cooldown pass where allocator trim still runs.

Commit structure

1. docs(research): record #110 memory-runtime preflight
2. fix(mem-trim): restore low-water and GC policy
3. feat(mem-trim): restore fail-open runtime diagnostics

Closes #110

[github-actions]

૮ >ﻌ< ა ci review

_{ran on ec4b510 — feat(mem-trim): restore fail-open runtime diagnostics}

❌ Job failures

Python tests / Run tests slice 12/12 · View job

Job Python tests / Run tests slice 12/12 failed.

---

⚠️ Warnings

OSV vulnerability scan · View job

5 known vulnerabilities found in pinned dependencies.

• CVE-2026-67213 in package-lock.json
• CVE-2026-67213 in website/package-lock.json
• CVE-2026-70608 in package-lock.json
• CVE-2026-56876 in package-lock.json
• CVE-2026-70606 in package-lock.json

How to fix:

Review the findings in the Security tab. Update the affected dependencies if a patched version is available.

---

debug info

CI timings

CI timings · View report · View job

Wall time 3m45s vs 3m25s (+9.8%). 11 job(s) slower, 13 faster,

• Python tests / Run tests slice 12/12: -135.0s
• Python tests / Run tests slice 7/12: -48.0s
• Python tests / Run tests slice 5/12: -29.0s
• Python tests / Run tests slice 3/12: -16.0s
• OS-specific tests / macOS-only tests: +12.0s

[Skywind5487]

Feature composition refreshed to current fork \main\ (\243352e7b).

• Rebased all 3 commits onto current \main\ (\�0f231813\ research, \