hermes - 💡(How to fix) Fix TUI automatic heap dumps can fill disk; add opt-in or retention guard

Summary

hermes --tui can repeatedly create very large V8 heap snapshot files under ~/.hermes/heapdumps when the TUI memory monitor hits auto-high or auto-critical. In a real local install this directory grew to tens of GiB.

This is adjacent to the already-closed TUI native memory leak issue:

• https://github.com/NousResearch/hermes-agent/issues/15141

That issue describes the native RSS leak and notes that heap dumps were being created repeatedly with little diagnostic value. Even if the underlying native leak is fixed, the automatic dump behavior still needs a disk-safety guard: large heap snapshots should not be written repeatedly without explicit opt-in, retention limits, or a disk budget.

Environment

• Hermes: v0.13.0 (2026.5.7) local install, with local guard patch
• OS: macOS
• TUI: hermes --tui
• Heapdump directory: ~/.hermes/heapdumps

Observed behavior

When the TUI memory monitor triggers automatic heap dumps, Hermes can write multi-GiB .heapsnapshot files under ~/.hermes/heapdumps. Repeated automatic triggers can consume tens of GiB without further user confirmation.

This is especially risky for native/RSS leaks because V8 heap snapshots may be large while not capturing the actual native-memory root cause.

Expected behavior

Automatic heap dumps should not be able to fill the user's disk by default.

Reasonable fixes could include one or more of:

• Make automatic heap dumps opt-in, e.g. HERMES_AUTO_HEAPDUMP=1.
• Keep manual heap dumps unchanged.
• Add retention limits by count/age/bytes under ~/.hermes/heapdumps.
• Add a minimum cooldown between automatic heap dumps.
• Prefer lightweight diagnostics JSON for automatic memory alarms, and only write full heap snapshots after explicit user opt-in.

Local mitigation

I patched ui-tui/src/lib/memory.ts locally so automatic triggers are disabled unless explicitly enabled:

const isAuto = trigger === 'auto-critical' || trigger === 'auto-high'
const autoEnabled = /^(?:1|true|yes|on)$/i.test((process.env.HERMES_AUTO_HEAPDUMP ?? '').trim())

if (isAuto && !autoEnabled) {
  return {
    error: 'automatic heap dumps disabled; set HERMES_AUTO_HEAPDUMP=1 to enable',
    success: false
  }
}

After rebuilding the TUI, a direct call to performHeapDump("auto-high") returns the guard error and ~/.hermes/heapdumps stays at 8.0K.

Why this should be separate from #15141

#15141 was closed as resolved by long-session TUI stabilization work, but the disk-safety problem is a separate invariant: even if memory pressure is caused by a future regression, automatic heap snapshots should have a default cap or opt-in guard so Hermes cannot silently consume tens of GiB.