[Yi-111-a]

Summary

On Windows + Node >= 24, omniroute update (and the doctor's version check) print a deprecation warning on every run:

(node:NNNN) [DEP0190] DeprecationWarning: Passing args to a child process with shell
option true can lead to security vulnerabilities, as the arguments are not escaped,
only concatenated.

It is cosmetic, but it shows up on the command whose whole job is diagnosing the install, so it reads like the tool reporting a fault with itself.

Two earlier fixes collided:

• [BUG] omniroute update fails on Windows — 'Could not check latest version' (execFile npm without shell in update.mjs, Node 24+ hardening, same class as #5379) #11335 enabled shell on win32 so npm.cmd can be spawned at all — Node >= 24 refuses a .cmd without one (Command run failed with error : spawn EINVAL nodejs/node#52554).
• But bin/cli/commands/update.mjs kept the argv-array call shape, and Node's normalizeSpawnArguments warns on exactly that combination: options.shell set and args.length > 0.

The shell is therefore required for the .cmd shim and deprecated alongside an argv array — the argv array #11335 kept passing is the one thing that cannot go through execFile with the shell enabled.

Fix

Node builds that command line itself in this path (${file} ${args.join(" ")}), so the same string is now handed over pre-joined with an empty args array. npmExecInvocation() returns the exact execFile arguments for a platform:

platform	file	args	options
win32	npm.cmd view omniroute version --prefer-online	[]	{ shell: true, windowsHide: true, timeout }
others	npm	["view", "omniroute", "version", "--prefer-online"]	{ shell: false, timeout }

Byte-identical input to the shell, minus the deprecation — the npm.cmd spawn from #11335 is untouched, so the original spawn EINVAL cannot come back.

Hard Rule #13 is now enforced rather than assumed. The shell is handed a raw string, so joining one is only safe while every token is a literal. A token outside a literal grammar (whitespace, a quote, a cmd/POSIX metacharacter, a backslash) throws instead of being concatenated, and the error names escapeWindowsShellArg() from bin/cli/utils/winShellArgs.mjs — the helper #15327 points at — or the environment. A caller that genuinely has a runtime value fails loudly instead of letting the shell reinterpret it.

Off Windows the argv array is returned verbatim and the tokens are not inspected at all, so the platforms that never needed a shell inherit no new restriction.

Scope is the CLI (bin/cli/), as reported. The server-side runNpm() in src/lib/services/installers/utils.ts passes a runtime args array with shell: true too; moving that to a joined string needs its --prefix/version handling reworked first, so it is left alone here rather than half-done.

Related Issues

• Closes fix(nodejs): Windows npm spawn passes an argv array with shell:true — Node 24 prints DEP0190 on omniroute update/doctor #15327
• Related to [BUG] omniroute update fails on Windows — 'Could not check latest version' (execFile npm without shell in update.mjs, Node 24+ hardening, same class as #5379) #11335 (the npm.cmd-needs-a-shell fix this collides with), Node warning after upgrading to v3.8.51 #15315, Omniroute 3.8.50 intermittently going offline #14240

Validation

• Change type: CLI
• Focused tests and category gates from the golden path
• Reconciled with the current active release base (release/v3.8.52)
• Production-code changes include a new or updated automated test in this PR

⚠️ base-red inherited: #15306 (release/v3.8.52 is already red before this PR).

Node ≥ 22 is required to observe the deprecation itself, and it is emitted at most once per process, so the regression guard asserts the property Node keys the warning on — no argv array travels with shell: true — rather than trying to capture the warning. Also checked out-of-band that both shapes really spawn and produce identical stdout (echo hello world -> hello world on both paths).

Not run locally: npm run lint, npm run typecheck:core and the full npm run test:unit. This checkout has no node_modules and the disk is at 98%, so the suite could not be installed; CI covers all three.

Tests Added Or Updated

• tests/unit/cli-npm-exec-dep0190-15327.test.ts (new) — the regression guard. TDD: 7 of its 9 tests fail against the pre-fix tree and all 9 pass after (the 2 that passed before are the unchanged-behavior controls). Covers: win32 passes no argv array with shell: true; the joined string carries every literal token verbatim with no quoting added or dropped; non-win32 keeps the argv array untouched; npmExecInvocation refuses ten non-literal shapes (&&, ;, |, $( ), backticks, embedded space, both quote characters, a C:\Users\John Doe\... path, ^&calc) while passing them through on linux; the twelve literal shapes the CLI actually spawns are still accepted; both npm call sites in update.mjs route through the helper; getLatestVersion passes no argv array on win32 and still keeps it off win32; and the shell is still enabled exactly where [BUG] omniroute update fails on Windows — 'Could not check latest version' (execFile npm without shell in update.mjs, Node 24+ hardening, same class as #5379) #11335 needed it.
• tests/unit/cli-update-npm-win32-11335.test.ts (updated) — its two structural assertions pinned the argv-array call shape that fix(nodejs): Windows npm spawn passes an argv array with shell:true — Node 24 prints DEP0190 on omniroute update/doctor #15327 has to remove, so they now assert the new invariant: every npmBin() call site goes through npmExecInvocation(), update.mjs no longer builds npm exec options itself, and the argv arrays it passes stay literal. Its behavioural assertions ([BUG] omniroute update fails on Windows — 'Could not check latest version' (execFile npm without shell in update.mjs, Node 24+ hardening, same class as #5379) #11335 npm.cmd + shell, non-win32 shell off, the --prefer-online install-mode strings) are unchanged and still pass.

Coverage Notes

bin/ is covered by the two files above. The new export is pure and fully exercised on both platform branches plus its rejection path; the only uncovered line would be the args ?? [] default, which no caller uses.

Reviewer Notes

• The one deliberate judgement call: npmExecInvocation throws on a non-literal token instead of quoting it. Escaping would need the double-caret rule escapeWindowsShellArg already implements for a different caller, and silently applying it to a value that was never validated would be the more dangerous default. Both current call sites pass literals, so nothing changes for them today — the throw is there so the next caller cannot quietly break Hard Rule deps: bump qs from 6.14.1 to 6.14.2 #13.
• getLatestVersion() gained an optional second platform parameter (defaults to process.platform) so the win32 path is testable from a non-Windows runner. Existing single-argument callers and tests are unaffected.
• The two printPostApplyGuidance lines Prettier wants to rewrap are pre-existing violations in the base file and were deliberately left alone to keep this diff to the defect.