Discussion: does the cli-entry.js --expose-gc wrapper earn the extra process?

[yiliang114]

This is a discussion / follow-up issue, not a bug report. Release is already unblocked by #5153 — nothing here is urgent or blocking. Just capturing a design question from #4914 so it isn't lost in a merged-PR thread.

Context. To make global.gc() available in production npm installs, #4914 added a dist/cli-entry.js bin wrapper that re-spawns node --expose-gc cli.js (and forwards args/stdio/signals). This is the OOM-prevention hardening, and the goal is clearly worth doing.

The question. Is the wrapper the right way to get there? The cost is a second node process held for the whole CLI lifetime, plus the manual forwarding. Meanwhile the compaction is doing the real OOM work, and the code already degrades gracefully when gc() isn't available (memoryPressureMonitor.ts just logs and skips). So it's worth asking whether the extra process is buying enough to justify itself.

Possible directions (just to seed discussion, not a proposal):

• Keep --expose-gc for dev/opt-in only, and rely on graceful degradation in production — no wrapper.
• Expose gc at runtime instead of via a launch flag (v8.setFlagsFromString('--expose_gc') + vm.runInNewContext('gc')) — one line, no wrapper, no extra process.
• Keep the wrapper as-is if there's a reason production explicit-gc is important enough to warrant it.

No strong opinion on the outcome — mainly want to make sure the tradeoff gets a deliberate look. Refs #4914, #5153.

中文说明

这是一个讨论 / follow-up issue，不是 bug。 release 已由 #5153 解锁，这里的内容都不紧急、不阻塞。只是把 #4914 的一个设计问题记下来，免得埋在已合并的 PR 讨论里。

背景。 为了让生产 npm 安装里 global.gc() 可用，#4914 加了个 dist/cli-entry.js wrapper，它会 re-spawn node --expose-gc cli.js（并转发参数/stdio/信号）。这是 OOM 加固，目标本身明确值得做。

问题。 wrapper 是不是实现这个目标的合适方式？代价是常驻一个跑满整个 CLI 生命周期的第二个 node 进程，外加手动转发。而真正防 OOM 的是 compaction，且 gc() 不可用时代码本来就优雅降级（memoryPressureMonitor.ts 只是 log 一下跳过）。所以值得问一句：这个额外进程换来的收益，够不够撑起它自己。

几个可能方向（只为引出讨论，不是定论）：

• --expose-gc 只留给 dev/opt-in，生产靠优雅降级——不要 wrapper。
• 运行时暴露 gc 而非靠启动 flag（v8.setFlagsFromString('--expose_gc') + vm.runInNewContext('gc')）——一行，无 wrapper、无额外进程。
• 如果有理由认为生产显式 gc 足够重要，也可以维持现状。

对结论没有强偏好，主要想确保这个取舍被认真看一眼。Refs #4914、#5153。

[qwen-code-ci-bot]

Triage

• Type: design discussion (enhancement)
• Labels: type/enhancement, category/performance, scope/memory-usage, priority/P3, need-discussion
• Next: Maintain discussion — no immediate action needed

Analysis

The question is well-framed and the code supports the claims. Here's what I found after reading the relevant source:

The wrapper's actual cost. cli-entry.js uses spawnSync — the parent process sits idle for the entire CLI lifetime, holding a second V8 heap just to forward exit codes and signals. The comment in cli-entry.js says --expose-gc has "zero runtime cost," which is true for the flag itself but ignores the wrapper process overhead (~20-30 MB for the idle parent V8 instance).

Graceful degradation already exists. In memoryPressureMonitor.ts:694-703, when global.gc is unavailable, the code logs a debug warning and skips. This means production installs without the wrapper would lose only the trigger_gc step in aggressive cleanup — compaction (the real OOM defense) still works.

The runtime flag alternative is viable. The v8.setFlagsFromString('--expose_gc') + vm.runInNewContext('gc') approach mentioned in the issue is a known Node.js technique. It would eliminate the wrapper entirely with a ~2-line change in memoryPressureMonitor.ts. The tradeoff is that it mutates V8 flags at runtime rather than at process launch — but since trigger_gc only fires at critical pressure (RSS ≥ 80%), this seems acceptable.

Stage 2: Verification

Source-level confirmation of key claims:

1. trigger_gc only fires at critical pressure — confirmed in memoryPressureMonitor.ts:453-462. The trigger_gc cleanup step is only included in the critical pressure tier (RSS ≥ 80%). Hard and soft pressure don't include it at all.

2. enableExplicitGC defaults to true — confirmed in memoryPressureMonitor.ts:212. It can be disabled via QWEN_MEMORY_ENABLE_GC=false env var (config.ts:1001-1006).

3. Removing the wrapper only affects direct npm installs — confirmed. acp-bridge/spawnChannel.ts:31 independently passes --expose-gc to channel subprocesses. Standalone packages (create-standalone-package.js:497,506) hardcode --expose-gc in their launcher scripts. Only the npm bin entry (cli-entry.js) would be affected.

4. Wrapper complication is real — PR fix(release): allow cli-entry.js in standalone dist allowlist #5153 (currently open) is already needed to fix a packaging allowlist issue caused by adding cli-entry.js. This is direct evidence of the wrapper's packaging cost.

Verdict: The code-level evidence strengthens the case for reconsidering the wrapper. The graceful degradation path is already well-tested (the memoryPressureMonitor.test.ts suite covers the no-gc case extensively). The wrapper's value-add is narrow (only critical-pressure GC, only for direct npm installs), while its cost spans the entire CLI lifetime and the packaging pipeline.

Refs: #4914, #5153

中文说明

分诊

• 类型: 设计讨论（enhancement）
• 标签: type/enhancement, category/performance, scope/memory-usage, priority/P3, need-discussion
• 下一步: 维持讨论——不需要立即行动

分析

问题提得很好，代码也支持这些论点。阅读相关源码后的发现：

wrapper 的实际代价。 cli-entry.js 使用 spawnSync——父进程在整个 CLI 生命周期内空闲等待，只为转发退出码和信号，同时持有第二个 V8 堆（约 20-30 MB）。cli-entry.js 注释说 --expose-gc "零运行时开销"，这对 flag 本身是对的，但忽略了 wrapper 进程的开销。

优雅降级已经就位。 memoryPressureMonitor.ts:694-703 中，当 global.gc 不可用时，代码只是打 debug 日志然后跳过。这意味着没有 wrapper 的生产安装只会丢失 aggressive cleanup 中的 trigger_gc 步骤——真正防 OOM 的 compaction 仍然正常工作。

运行时 flag 替代方案可行。 issue 中提到的 v8.setFlagsFromString('--expose_gc') + vm.runInNewContext('gc') 是已知的 Node.js 技术。只需在 memoryPressureMonitor.ts 改约 2 行就能完全去掉 wrapper。代价是在运行时而非进程启动时修改 V8 flags——但考虑到 trigger_gc 只在 critical pressure（RSS ≥ 80%）时触发，这似乎可以接受。

第二阶段：验证

源码级关键论点确认：

1. trigger_gc 只在 critical pressure 时触发 — 在 memoryPressureMonitor.ts:453-462 确认。trigger_gc cleanup step 只包含在 critical 层级（RSS ≥ 80%）中。Hard 和 soft 压力完全不包含它。

2. enableExplicitGC 默认为 true — 在 memoryPressureMonitor.ts:212 确认。可通过 QWEN_MEMORY_ENABLE_GC=false 环境变量禁用（config.ts:1001-1006）。

3. 移除 wrapper 只影响直接 npm 安装 — 确认。acp-bridge/spawnChannel.ts:31 独立地向 channel 子进程传递 --expose-gc。Standalone 包（create-standalone-package.js:497,506）在启动器脚本中硬编码了 --expose-gc。只有 npm bin 入口（cli-entry.js）会受影响。

4. Wrapper 的打包复杂度是真实的 — PR fix(release): allow cli-entry.js in standalone dist allowlist #5153（当前 open）正是为了修复添加 cli-entry.js 导致的打包白名单问题。这是 wrapper 打包成本的直接证据。

结论： 代码级证据加强了重新考虑 wrapper 的合理性。优雅降级路径已经过充分测试（memoryPressureMonitor.test.ts 测试套件广泛覆盖了无 gc 场景）。Wrapper 的价值很窄（仅 critical-pressure GC，仅直接 npm 安装），而代价跨越整个 CLI 生命周期和打包流程。

— Qwen Code · qwen3.7-max