Skip to content

Commit 1aa0aeb

Browse files
authored
fix(cli): stop Node 24/26 process exits from hanging after output (#163788)
On Node 24 and 26, process.exit() joins V8's platform workers without disposing the isolate. A concurrent Maglev or Sparkplug compile job parked waiting for a main-thread GC then never finishes, so CLI commands, the hook relay, or a stopping Gateway can sit at 0% CPU forever after printing their output (nodejs/node#64274; fix pending in nodejs/node#66171). Every OpenClaw executable entrypoint (CLI entry, Gateway/service index, native hook relay, macOS node worker) now turns off Maglev and concurrent Sparkplug at startup when it runs as main, matching Node 22's tiering and the existing Vitest policy. Library imports keep stock V8; explicit --maglev or --concurrent-sparkplug flags still win. Testbox A/B (4 vCPU, Node 24.19, e2e CLI child replay, 8-way): 6/1019 hung with defaults, 0/1019 with the policy; re-enabling only Maglev hung 2/1019 and only concurrent Sparkplug 12/944, so both flags are needed.
1 parent d1148df commit 1aa0aeb

6 files changed

Lines changed: 46 additions & 6 deletions

File tree

‎docs/install/node-compatibility.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,10 @@ The **SQLite WAL-reset corruption bug** requires a safe loaded library: SQLite *
4343

4444
Separately, the **`node:sqlite` TEXT decoder** in Node 22.23.x, 24.15.0, 25.9.0, and 26.0.0 silently truncates values at embedded NUL characters. The first fixed releases are Node 24.16.0 and 26.1.0; a WAL-safe SQLite library does not fix this decoder. Node 23 was excluded earlier for incompatible `node:sqlite` behavior.
4545

46+
## V8 compiler settings
47+
48+
On Node 24 and 26, `process.exit()` can hang forever after a command has printed its output: Node joins V8's background threads while a Maglev or concurrent Sparkplug compile job waits for a garbage collection the exiting main thread never runs ([nodejs/node#64274](https://github.com/nodejs/node/issues/64274)). OpenClaw's CLI, Gateway, hook relay, and macOS node worker therefore start with Maglev and concurrent Sparkplug turned off, the tiering Node 22 used; TurboFan still optimizes hot code. Passing `--maglev` or `--concurrent-sparkplug` to `node` keeps that compiler enabled.
49+
4650
## Platform consequences
4751

4852
Official Node 24+ macOS binaries are built for **macOS 13.5+**, the oldest release Node supports. macOS does not block them on older releases, and the CLI and Gateway have been observed running on macOS 12 with official Node 24. OpenClaw does not test or support macOS 11 through 13.4, so features that ship their own native binaries can still fail there. The companion app has separate [macOS requirements](/platforms/macos).
Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
// V8 compiler tiering for OpenClaw process entrypoints that end in process.exit().
2+
import { setFlagsFromString } from "node:v8";
3+
4+
// process.exit() joins V8's platform workers without disposing the isolate. A
5+
// concurrent Maglev or Sparkplug job parked waiting for a main-thread GC then
6+
// never finishes, so the process hangs after its output (nodejs/node#64274;
7+
// fix pending in nodejs/node#66171). Node 22 ran without both; switch them off
8+
// before commands start compiling hot code. An explicit operator flag wins.
9+
const EXIT_UNSAFE_COMPILERS = [
10+
{ disable: "--no-maglev", enable: "--maglev" },
11+
{ disable: "--no-concurrent-sparkplug", enable: "--concurrent-sparkplug" },
12+
] as const;
13+
14+
/** Keeps V8 compile jobs that can deadlock process.exit() off background threads. */
15+
export function disableExitUnsafeCompilers(): void {
16+
if (process.versions.bun) {
17+
return;
18+
}
19+
const explicit = new Set(process.execArgv.map((arg) => arg.replaceAll("_", "-")));
20+
for (const { disable, enable } of EXIT_UNSAFE_COMPILERS) {
21+
if (!explicit.has(enable)) {
22+
setFlagsFromString(disable);
23+
}
24+
}
25+
}

‎src/cli/native-hook-relay-entry.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
#!/usr/bin/env node
22
// Dedicated cold-process entrypoint for native provider hook relays.
33
import process from "node:process";
4+
import { disableExitUnsafeCompilers } from "../bootstrap/node-exit-safe-compilers.js";
45
import { drainProcessOutput } from "../process/output-drain.js";
56
import { runNativeHookRelayCliFromArgv } from "./native-hook-relay-cli.js";
67

8+
disableExitUnsafeCompilers();
79
process.title = "openclaw-hooks";
810
let exitCode = 1;
911
try {

‎src/entry.ts‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
import process from "node:process";
55
import { fileURLToPath } from "node:url";
66
import { format } from "node:util";
7+
import { disableExitUnsafeCompilers } from "./bootstrap/node-exit-safe-compilers.js";
78
import { resolveCliArgvInvocation } from "./cli/argv-invocation.js";
89
import { isRootHelpInvocation } from "./cli/argv.js";
910
import { parseCliContainerArgs, resolveCliContainerTarget } from "./cli/container-target.js";
@@ -122,12 +123,14 @@ const gatewayEntryStartupTrace = createGatewayDispatchStartupTrace(process.argv,
122123
// is the actual entry point; without this guard the top-level code below
123124
// would call runCli a second time, starting a duplicate gateway that fails
124125
// on the lock / port and crashes the process.
125-
if (
126-
!isMainModule({
127-
currentFile: fileURLToPath(import.meta.url),
128-
wrapperEntryPairs: [...ENTRY_WRAPPER_PAIRS],
129-
})
130-
) {
126+
const isEntryMain = isMainModule({
127+
currentFile: fileURLToPath(import.meta.url),
128+
wrapperEntryPairs: [...ENTRY_WRAPPER_PAIRS],
129+
});
130+
if (isEntryMain) {
131+
disableExitUnsafeCompilers();
132+
}
133+
if (!isEntryMain) {
131134
// Imported as a dependency — skip all entry-point side effects.
132135
} else if (isUpdateAdmissionInvocation(resolveCliArgvInvocation(process.argv))) {
133136
await tryRunUpdateAdmissionBeforeStartup(resolveCliArgvInvocation(process.argv));

‎src/index.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import { existsSync } from "node:fs";
44
// Package executable entrypoint that forwards to the CLI bootstrap.
55
import process from "node:process";
66
import { fileURLToPath } from "node:url";
7+
import { disableExitUnsafeCompilers } from "./bootstrap/node-exit-safe-compilers.js";
78
import { resolveCliArgvInvocation } from "./cli/argv-invocation.js";
89
import { tryRunUpdateAdmissionBeforeStartup } from "./cli/run-main-update-admission.js";
910
import {
@@ -16,6 +17,9 @@ import { isMainModule } from "./infra/is-main.js";
1617
const isMain = isMainModule({
1718
currentFile: fileURLToPath(import.meta.url),
1819
});
20+
if (isMain) {
21+
disableExitUnsafeCompilers();
22+
}
1923
const handledAdmission =
2024
isMain && (await tryRunUpdateAdmissionBeforeStartup(resolveCliArgvInvocation(process.argv)));
2125
const packageRootUrl = new URL("../", import.meta.url);

‎src/node-host/mac-worker-entry.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
// Sealed CLI composition root for the private macOS app node-host worker.
33
import process from "node:process";
44
import { fileURLToPath } from "node:url";
5+
import { disableExitUnsafeCompilers } from "../bootstrap/node-exit-safe-compilers.js";
56
import { ensureCliExecutionBootstrap } from "../cli/command-execution-startup.js";
67
import { resolveCliStartupPolicy } from "../cli/command-startup-policy.js";
78
import { loadCliDotEnv } from "../cli/dotenv.js";
@@ -82,6 +83,7 @@ async function runMacNodeWorkerEntry(argv: string[] = process.argv): Promise<voi
8283
}
8384

8485
if (isMainModule({ currentFile: fileURLToPath(import.meta.url) })) {
86+
disableExitUnsafeCompilers();
8587
// The worker records its exit request after draining runtime-owned resources.
8688
// Finalize it here so plugin-owned pipes cannot pin shutdown or startup failure.
8789
await runCliWithExitFinalization({

0 commit comments

Comments
 (0)