fix(tui): harden against Node V8 OOM + GatewayClient leaks + resize perf

[OutThisLife]

Summary

Two classes of TUI pain folded into one branch:

1. Long-session V8 OOM + GatewayClient memory leaks — transcripts + reasoning blobs would cross the default (~1.5–4 GB) V8 heap cap and fatal-OOM; GatewayClient's RPC timeout closures and unbounded splice'd event/log arrays bled memory during bursts.
2. Resize lag — VSCode panel-drag fires 20+ SIGWINCHes/sec, each firing an unthrottled terminal.resize gateway RPC and re-running useVirtualHistory with a now-wrong height cache → 200–600 ms React commit block + visible black flash.

Defense-in-depth for both, plus a /heapdump + /mem for when things do go sideways.

---

1 — Memory hardening

Heap budget — never crash on OOM again

• hermes_cli/main.py _launch_tui() injects NODE_OPTIONS=--max-old-space-size=8192 --expose-gc, appending (not clobbering) any user-provided NODE_OPTIONS. Covers both node dist/entry.js and tsx src/entry.tsx paths.
• ui-tui/src/entry.tsx shebang upgraded to #!/usr/bin/env -S node --max-old-space-size=8192 --expose-gc as a fallback for direct invocation.

GatewayClient leak-proofing

• setMaxListeners(0) in the constructor — silences spurious warnings caused by legitimate multi-listener hook patterns.
• CircularBuffer for logs and bufferedEvents — O(1) fixed-capacity push; kills the hot-path array.splice(0, n) copy churn under bursty stderr.
• RPC timeout refactor — replaces the inline arrow that captured method/params/resolve/reject for the full 120 s request timeout:
  • setTimeout(this.onTimeout.bind(this), REQUEST_TIMEOUT_MS, id) — the bound handler only closes over this and id.
  • Each Pending record owns its timeout handle, .unref()'d so stuck requests don't keep the event loop alive.
  • rejectPending() now clears timers (previously leaked the timer itself on gateway exit/error).

Memory diagnostics (new)

• ui-tui/src/lib/memory.ts
  • performHeapDump() + captureMemoryDiagnostics() — writes both a V8 .heapsnapshot and a .diagnostics.json sidecar to ~/.hermes/heapdumps/ (override via HERMES_HEAPDUMP_DIR). Diagnostics written before the snapshot so we still get useful info if snapshot serialization crashes on large heaps.
  • Diagnostics capture: detached V8 contexts (closure-leak signal), active handles/requests via process._getActiveHandles()/_getActiveRequests(), Linux /proc/self/fd count + /proc/self/smaps_rollup, heap growth rate (MB/hr), and auto-classifies likely leak sources.
• ui-tui/src/lib/memoryMonitor.ts — 10 s polling loop:
  • heapUsed ≥ 1.5 GB → auto heap dump (trigger auto-high)
  • heapUsed ≥ 2.5 GB → final dump + process.exit(137) so the user can restart cleanly before V8 fatal-OOMs
  • Handle is .unref()'d; never holds the process open.

Graceful exit (new)

• ui-tui/src/lib/gracefulExit.ts
  • SIGINT/SIGTERM/SIGHUP run registered cleanups through a 4 s failsafe setTimeout that hard-exits if cleanup hangs (WSL / tmux SIGHUP flakiness gets caught here).
  • uncaughtException / unhandledRejection log to stderr instead of crashing — a transient TUI render error should not kill an in-flight agent turn.

Slash commands (new)

• /heapdump — manual snapshot + diagnostics with paths echoed into the transcript.
• /mem — live heap / heapTotal / external / arrayBuffers / rss / uptime panel.

Utility (new)

• ui-tui/src/lib/circularBuffer.ts — small fixed-capacity ring (push / tail(n) / drain() / clear()). Replaces ad-hoc array.splice(0, len - MAX) pattern.

---

2 — Resize perf

terminal.resize RPC debounce — ui-tui/src/app/useMainApp.ts

• 100 ms trailing debounce. React cols state stays sync (Yoga / in-process rendering needs it); only the round-trip to Python coalesces. Stops gateway flood during panel-drag / tmux-pane-resize.

Column-aware useVirtualHistory — ui-tui/src/hooks/useVirtualHistory.ts

New required columns param, plumbed through from useMainApp. Three coordinated fixes:

1. Scale cached heights by oldCols/newCols on column change. Clearing instead would force a pessimistic back-walk mounting ~190 rows at once — each a fresh marked.lexer + syntax highlight ≈ 3 ms → ~600 ms React commit block. Scaled heights keep the back-walk tight.
2. freezeRenders=2: reuse pre-resize mount range for 2 renders so already-mounted MessageRows keep their warm useMemo results. Without this the first post-resize render unmounts + remounts most rows = visible flash + 150 ms+ freeze.
3. skipMeasurement flag: first post-resize useLayoutEffect would read pre-resize Yoga heights (Yoga's stored values are still from the frame before this render's calculateLayout with the new width) and poison the scaled cache. Skip the measurement loop for that one render; next render's Yoga is correct.

The renderer-level patterns (sync-dim-capture + microtask-coalesced React commit, atomic BSU/ESU erase-before-paint, mouse-tracking reassert, iTerm2 ?1049h avoidance) already live in hermes-ink's own handleResize; this patch adds the matching app-layer hygiene.

---

Env knobs

Var	Effect
NODE_OPTIONS	existing value respected and appended to, not replaced
HERMES_HEAPDUMP_DIR	override snapshot output directory
HERMES_HEAPDUMP_ON_START=1	dump once at boot (baselining)

Test plan

• tsc --noEmit -p tsconfig.json clean
• vitest run — 15 files, 102 tests passing
• eslint clean on all new / touched files
• tsc -p tsconfig.build.json produces executable dist/entry.js with the shebang preserved
• Smoke test: HERMES_HEAPDUMP_DIR=/tmp/hh performHeapDump('manual') → valid .heapsnapshot + .diagnostics.json with detachedContexts, activeHandles, smapsRollup.
• Long-session repro — 1000+ message session with large tool outputs; confirm (a) no OOM, (b) /mem below 1.5 GB, (c) /heapdump produces a useful snapshot if it does leak.
• Resize repro — drag a VSCode terminal panel / tmux pane during a long session; confirm no black flash + no RPC storm in gateway logs.
• Confirm Ctrl+C / terminal-close still exits cleanly within the 4 s failsafe.

[Copilot]

Pull request overview

This PR hardens the Hermes TUI against long-session memory growth (Node/V8 heap limits + GatewayClient leaks) and improves resize responsiveness by reducing gateway RPC churn and stabilizing virtualized transcript rendering during column changes.

Changes:

• Adds heapdump + memory diagnostics utilities (manual /heapdump, /mem, plus automatic dumps/exit on high/critical memory).
• Refactors GatewayClient to reduce memory churn/leaks (bounded buffers, safer timeout handling, clears timers on rejection).
• Improves resize performance (debounced terminal.resize RPC; column-aware virtual history with scaled cached heights + temporary render/measurement freezing).

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
ui-tui/src/lib/memoryMonitor.ts	Adds periodic heap monitoring with auto-dump triggers.
ui-tui/src/lib/memory.ts	Implements heap snapshot + diagnostics capture and byte formatting helpers.
ui-tui/src/lib/gracefulExit.ts	Adds signal handling + cleanup + failsafe exit wiring.
ui-tui/src/lib/circularBuffer.ts	Introduces fixed-capacity buffer to prevent unbounded log/event growth.
ui-tui/src/hooks/useVirtualHistory.ts	Makes virtualization column-aware; scales cached row heights across resizes to avoid heavy remount/measurement.
ui-tui/src/gatewayClient.ts	Uses circular buffers for logs/events; refactors RPC timeout lifecycle to reduce leaks.
ui-tui/src/entry.tsx	Wires memory monitor + graceful exit; adds memory/OOM resilience; updates shebang with heap flags.
ui-tui/src/app/useMainApp.ts	Debounces terminal.resize RPC and plumbs column count into virtualization hook.
ui-tui/src/app/slash/registry.ts	Registers new debug slash commands.
ui-tui/src/app/slash/commands/debug.ts	Adds /heapdump and /mem commands for live diagnostics.
hermes_cli/main.py	Appends Node heap/GC options when launching the TUI.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.