PR #17200: fix(tui): pass --expose-gc as a node CLI flag, not via NODE_OPTIONS (#17187)

• Repository: NousResearch/hermes-agent
• Author: briandevans
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/17200

Description (problem / solution / changelog)

Summary

• hermes --tui immediately exits with --expose-gc is not allowed in NODE_OPTIONS on Node ≥ 20 because the launcher set NODE_OPTIONS="--max-old-space-size=8192 --expose-gc" (added in #13231).
• Move --expose-gc from the env var onto the node argv inside _make_tui_argv for the two node-direct launch paths. Keep --max-old-space-size=8192 in NODE_OPTIONS, where it's allowed and where user overrides still merge correctly.
• Adds 4 regression tests (env-var construction + both node-direct argv branches).

The bug

hermes_cli/main.py:1126-1136 (pre-fix) appended --expose-gc to whatever the user had in NODE_OPTIONS:

_tokens = env.get("NODE_OPTIONS", "").split()
if not any(t.startswith("--max-old-space-size=") for t in _tokens):
    _tokens.append("--max-old-space-size=8192")
if "--expose-gc" not in _tokens:
    _tokens.append("--expose-gc")
env["NODE_OPTIONS"] = " ".join(_tokens)

--expose-gc is a V8 flag. Node has an explicit allow-list for NODE_OPTIONS and refuses anything outside it on startup, so the spawned process aborts before the TUI loads:

$ hermes --tui
/home/cimon/.local/bin/node: --expose-gc is not allowed in NODE_OPTIONS

The reporter (#17187) hit this on Ubuntu 24.04 with Node 20.12.2, with their own NODE_OPTIONS empty — the launcher itself was the source. unset NODE_OPTIONS doesn't help because the launcher re-injects the flag every run.

--max-old-space-size=… is on Node's allow-list, which is why the cap added in #13231 still works; only the --expose-gc line trips the rejection.

The fix

_make_tui_argv already returns argv tuples like [node, dist/entry.js] for the two production paths (HERMES_TUI_DIR fast path + built-bundle fallback). V8 flags pass through fine when given on the node CLI, so the patch just inserts --expose-gc between the binary and the script:

return [node, "--expose-gc", str(p / "dist" / "entry.js")], p

…and drops the --expose-gc block from the NODE_OPTIONS construction in _launch_tui. --max-old-space-size=8192 continues to be set via env so the existing user-merge semantics (respect any user-supplied higher cap) are preserved.

The dev paths (tsx src/entry.tsx, npm start) aren't node-direct, so they don't pick up --expose-gc. Those paths are maintainer-only and were already broken on Node 20+ under the old code, so this is a pragmatic trade-off rather than a regression.

Test plan

• Focused regression test: tests/hermes_cli/test_tui_node_options_expose_gc.py — 4 tests covering the env-var construction in _launch_tui (no --expose-gc injected, user NODE_OPTIONS preserved without double-cap) and both node-direct branches of _make_tui_argv (HERMES_TUI_DIR + built bundle), each asserting --expose-gc lands on argv before the entry script. All 4 pass.
• Adjacent suite: tests/hermes_cli/test_tui_resume_flow.py, tests/hermes_cli/test_tui_npm_install.py, tests/hermes_cli/test_launcher.py — 17 / 17 pass on this branch.
• Regression guard: all 4 new tests fail on clean origin/main (188eaa57c) with the exact reporter symptom: AssertionError: --expose-gc must not be injected into NODE_OPTIONS (#17187); got NODE_OPTIONS='--max-old-space-size=8192 --expose-gc'. They pass with the fix applied.

Related

• Fixes #17187
• Follow-up to #13231 (which introduced the --expose-gc injection alongside the V8 heap cap).

Changed files

• hermes_cli/main.py (modified, +9/-9)
• tests/hermes_cli/test_tui_node_options_expose_gc.py (added, +166/-0)