[diegosouzapw]

Root cause

bin/omniroute.mjs imports getNodeRuntimeSupport/getNodeRuntimeWarning from
bin/nodeRuntimeSupport.mjs to detect an unsupported Node.js runtime, but never actually
calls either function — only bin/cli/commands/serve.mjs and bin/cli/commands/doctor.mjs
do, deep inside command handlers that are unreachable if the startup import chain itself crashes
first.

And it does crash first: right after generating STORAGE_ENCRYPTION_KEY, the script does
await import("tsx/esm") and then loads Commander's ~70 command modules (bin/cli/program.mjs),
which pull in ora -> the hoisted string-width@8.x. That package's index.js has top-level
regex literals using the ES2024 v (Unicode-set) flag, e.g. /^\p{RGI_Emoji}$/v. On a Node/V8
build that predates v-flag support, that literal fails to even parse, and V8 throws exactly
SyntaxError: Invalid regular expression flags — with no flag value in the message, which is why
it looked untraceable. Same class of failure hit pnpm (pnpm/pnpm#11546), root-caused there as
running a too-new dependency on an unsupported/old Node major.

Fix

Call the existing getNodeRuntimeSupport()/getNodeRuntimeWarning() check right after the
--version/-V fast path in bin/omniroute.mjs, before the heavy tsx/esm + command-
registration import chain. When the runtime is incompatible, print a clear, actionable message
(including a note that a stale/distro-packaged nodejs binary is the most common cause) and
process.exit(1). The check is skipped for the same read-only invocations
shouldProvisionStorageKey already exempts (--help/-h, help/completion) — those still
need the full command registry to render their own output, so an incompatible runtime crashing
there is a separate, pre-existing limitation this fix does not attempt to solve.

The existing calls in serve.mjs/doctor.mjs are left as-is (harmless duplicate checks).

Regression test

tests/unit/issue-12296-node-runtime-guard.test.ts — asserts bin/omniroute.mjs actually calls
getNodeRuntimeSupport/getNodeRuntimeWarning, and that the call happens before
await import("tsx/esm").

RED (before fix):

✖ bin/omniroute.mjs invokes the Node runtime compatibility guard before the heavy tsx/esm + command-registration import chain
AssertionError [ERR_ASSERTION]: getNodeRuntimeSupport()/getNodeRuntimeWarning() is imported in
bin/omniroute.mjs but never called there ...
  actual: -1, expected: -1 (notStrictEqual), tests 1, pass 0, fail 1

GREEN (after fix):

✔ bin/omniroute.mjs invokes the Node runtime compatibility guard before the heavy tsx/esm + command-registration import chain
tests 1, pass 1, fail 0

Gates run

• node scripts/check/check-file-size.mjs — OK
• node scripts/check/check-complexity.mjs — OK (2798 violations vs baseline 3218)
• node scripts/check/check-cognitive-complexity.mjs — OK (1265 violations vs baseline 1437)
• npm run typecheck:core — clean (exit 0)
• npx eslint --suppressions-location config/quality/eslint-suppressions.json <changed files> — clean (bin/** is excluded from ESLint's scope by project config; the new test file lints clean)
• New regression test — PASS (RED→GREEN evidence above)
• Existing CLI-entrypoint-touching tests re-run individually (not just the new test):
  cli-entrypoint, cli-version-fastpath, cli-storage-key-provision,
  cli-storage-key-bootstrap, bin-omniroute-mcp, cli-data-dir-env,
  cli-data-dir-env-loading, cli-env-collision, cli-update-notifier,
  cli-update-global-paths-3295, reset-password-cli-6261-6258,
  cli-electron-to-cli-migration-server-env-7302, termux-android-cache-dir,
  cli-memory, node-runtime-support — all pass.
  mcp-stdio-json-purity fails identically on both the fixed and the pre-fix (baseline) code
  under the current heavy multi-worktree devbox load (61s timeout waiting for the MCP subprocess
  to answer on stdout) — confirmed pre-existing/unrelated by reverting to HEAD:bin/omniroute.mjs
  and re-running the same test, which fails with the same timeout and message.
• node scripts/check/check-changelog-integrity.mjs — OK

⚠️ base-red inherited: #12732 — unit #12058, integration codex-cache, package-artifact, tarball-smoke, agent-skills-sync

Closes #12296