Proposal: Make Node 24 the minimum to match our TS7 modernization and reduce runtime overhead

[backryun]

I propose making a current, patched Node.js 24 release the minimum supported runtime for OmniRoute in the next announced breaking release, while retaining Node 26 compatibility testing. We should schedule this proactively, ahead of Node 22's end of life.

There is a concrete engineering case: align our runtime with the TS7 modernization already underway, close part of the gap between modern type declarations and runtime API availability, make a more efficient async-context implementation the default, and reduce the compatibility work attached to future server-side changes.

Repository references below are pinned to b345c7f6, inspected on September 7, 2026.

1. Match the runtime to the TS7 modernization already underway

OmniRoute has already invested in preparing its code for TypeScript 7. The runtime policy should support that direction. The recorded TS7 changes cover concrete contracts such as catalog rows, SQLite transaction state, executor configuration, and provider credentials. CI also blocks newly introduced TS7 diagnostics and runs a TS7 compiler check.

The current transition is deliberately hybrid: the main dependency is still TypeScript 6.0.3, while CI invokes TypeScript 7.0.2 separately. Existing TS7 diagnostics remain a tracked backlog. We have substantial TS7 preparation to build on, with further compiler migration work still ahead.

The concrete connection to Node 24 is closing part of the gap between the APIs our compiler knows and the APIs our supported runtimes actually provide. Our root configuration and streaming-engine configuration already use lib: esnext, target: ES2022, and noEmit: true. TypeScript's lib declarations describe APIs; they do not install their implementations in Node.

For example, a typed call to RegExp.escape(value) can be accepted with modern library declarations while still requiring that API at runtime. Node 24 provides it natively. This connects directly to the handwritten escaping helpers identified below: after consumer validation, a newer runtime floor lets us use the standard implementation and maintain fewer fallback paths. The same principle guides future server-side API adoption. Node 24 does not guarantee every esnext API, so minimum-runtime tests remain necessary.

The combined payoff is faster development feedback from TS7 adoption, a more capable minimum runtime, and fewer compatibility decisions for each future change. Microsoft's native-compiler performance work concerns compilation and editor tooling; Node 24's async-context improvement concerns running requests. These are complementary gains with separate measurements. Raising Node's floor alone neither accelerates TS7 by the compiler's advertised factor nor changes our current emitted output or removes TS6 tooling requirements.

That is why this is a useful next step in the modernization we have already started: give the TS7-ready codebase a runtime contract that makes more standard APIs usable across supported Node installations, and spend less future engineering effort preserving an older runtime path.

2. Node 24 is already our practical baseline

The declared runtime range still includes Node 22, but the repository has moved considerably further:

Area	Verified state
Declared runtime	package.json accepts `>=22.22.2 <23
Local development default	.nvmrc and .node-version select 24.
Main CI	CI_NODE_VERSION is 24.
Nightly core compatibility matrix	Already tests [24, 26].
Developer tooling	The locked license-checker-rseidelsohn@5.0.1 requires Node >=24 and npm >=11.

That last point is an existing tooling mismatch: Node 22 satisfies the application's advertised engine range but does not satisfy this development dependency's engine requirement. Our contributor toolchain already needs a newer baseline.

Keeping 22 supported means continuing to reason about behavior outside these core CI baselines, or investing in additional coverage. Raising the floor makes the support contract match what we routinely exercise. It also gives contributors a clearer answer to “which runtime can this change assume?”

3. A performance improvement that maps directly to OmniRoute

Node 24 makes AsyncLocalStorage use AsyncContextFrame by default. Node's release announcement describes this as a more efficient implementation, and the upstream implementation PR explicitly identifies improved AsyncLocalStorage performance as the motivation.

This matters to OmniRoute because async context is already part of its request plumbing:

• Proxy and TLS request context uses multiple AsyncLocalStorage instances.
• Request IDs and provider request logging propagate request-scoped state.
• Token refresh persistence also uses AsyncLocalStorage.

The performance opportunity is lower router-side async-context overhead under concurrency. Making 24 the floor brings that default implementation to installations still running 22, without requiring a redesign of our context propagation.

The mechanism is verified; OmniRoute's throughput gain is not yet measured. An engine-field change does not speed up an installation already running 24, and upstream LLM latency can hide router improvements. We should measure CPU per request, throughput, p95 router latency, and RSS using the same commit and a deterministic local upstream on patched 22 and 24. Those measurements will show how much of the upstream improvement translates into application-level capacity.

4. Less compatibility code—and less code we need to write next

The immediate policy edit is small. The continuing benefit is that new code no longer has to preserve a Node 22 implementation path.

There are concrete cleanup opportunities:

• Runtime policy bookkeeping: both the CLI runtime helper and the application runtime helper carry Node 22 entries and support text. Retiring that line removes a version-policy case from both surfaces and their tests.
• Native standard APIs: Node 24's V8 update supplies RegExp.escape. We already maintain a handwritten escaping helper in grokBuildConfig.ts, and another in the SVG validation script. These are concrete candidates for replacement after checking consumers and tests. The TC39 design handles composition edge cases beyond the familiar punctuation-replacement helper. Browser-delivered code and other supported runtimes need their own compatibility checks.
• One fewer native-addon ABI to support: our SQLite rebuild guard explicitly documents the Node 22/24 ABI mismatch. Dropping 22 removes that supported transition from troubleshooting and validation; Node 24/26 and Electron differences still justify keeping the guard.

The measurable immediate saving is a smaller set of runtime cases; the larger payoff is avoiding repeated compatibility branches, fallback helpers, and review work as the codebase evolves. Follow-up cleanup PRs should report actual deletions and preserved behavior.

There is also a bounded CI opportunity: the OpenCode plugin workflow runs two [22, 24] test matrices. If those separately published packages can adopt the same floor, their test jobs fall from four to two. That is 50% fewer jobs in those two matrices, conditional on host compatibility. The saving applies to those matrices only; main CI already runs 24.

5. Why act before Node 22 reaches EOL?

According to the official release schedule, Node 22 is in Maintenance LTS and reaches EOL on April 30, 2027. Node 24 is currently Active LTS and is scheduled to remain supported until April 30, 2028: a year longer.

Node 22 still receives security maintenance. The reason to move early is that waiting keeps the compatibility obligation in place while our toolchain and test baseline already favor 24. An announced transition now gives users migration time and lets maintainers start taking advantage of the newer contract sooner.

Proposed rollout

1. Announce Node 24 as the minimum for a named upcoming breaking release, with a short migration window. Select a currently patched 24.x minimum when implementing it; keep Node 26 coverage and make supported majors explicit.
2. Align package metadata, runtime guards, installation messages, documentation, and tests in one focused PR. Assess independently published plugins against their host requirements.
3. Validate clean installation, native SQLite loading, both unit-test runners, production build, streaming cancellation/context propagation, and proxy/TLS behavior. The official migration guide identifies relevant platform changes, including macOS 13.5 minimum and changes to official 32-bit binaries.
4. Follow with small, tested native-API cleanup PRs and a reproducible 22-versus-24 performance report. Run benchmarks with separate dependency installations for each native ABI.

I recommend scheduling this now. It aligns our stated support with our TS7 modernization and engineering baseline, brings a relevant runtime efficiency improvement to remaining Node 22 deployments, and reduces the compatibility work attached to future changes. Those benefits justify a deliberate transition before EOL; we can quantify the additional code and performance gains as follow-up work.

At the same time, let's move quickly on the large-scale test-suite cleanup and make a concerted effort to clear the accumulated development-environment debt in the near term. I have already opened a branch for that cleanup, and I hope the corresponding PR can be reviewed and merged soon. Coordinating this work with the Node 24 transition and our ongoing TS7 modernization would give us a more coherent development baseline and a more maintainable test suite. Let's prioritize getting these changes over the finish line, so future development benefits from a cleaner toolchain and test workflow as soon as possible.

[diegosouzapw]

Hey @backryun! Accepted — and thanks for pinning the references to a commit, that made this reviewable instead of a debate about vibes.

Landing at 3.9.0 LTS. Not mid-3.8.x, and not deferred to v4.0.

The reasoning is about when a break is legitimate, not about Node. Today engines.node is >=22.22.2 <23 || >=24.0.0 <27. Raising that floor inside a patch line breaks npm i -g omniroute for Node 22 users with no announcement they ever agreed to read — a patch release is the one place a runtime break is indefensible. Deferring it to v4.0, on the other hand, drags the TS7 gap you describe through the entire 3.9 line for no gain.

3.9.0 is the stabilization point before v4, and an announced runtime floor is exactly what an LTS boundary is for: users adopt it deliberately. So it lands there.

Tracking in #12939, with the full surface: package.json, .node-version/.nvmrc, the CI matrices (drop the 22 leg, keep 24 + 26), the Dockerfile base, the Electron bundled runtime, and the docs prerequisites.

Two conditions on the issue, both from things that already bit us:

1. nightly-compat green on 24 and 26 before the bump merges (🌙 nightly-compat: Node 24/26 failures on release/v3.8.51 #12713, 🌙 nightly-compat: Node 24/26 failures on release/v3.8.50 #9576). Raising the floor while the higher legs are red just moves the failure somewhere less visible.
2. No engines-strict bypass added to make CI pass. If the bump breaks a gate, the gate is telling the truth.

Also worth verifying rather than assuming: #11835 reported a pulled image running Node v20.20.2 despite the Dockerfile's 24+ base. Whatever causes that drift will happily survive the bump and produce an image below the new floor, so it gets checked as part of this.

Node 26 compatibility testing is retained.