Skip to content

fix: Windows CLI backends fail through npm shims#101378

Merged
steipete merged 6 commits into
mainfrom
codex/fix-windows-cli-shims
Jul 7, 2026
Merged

fix: Windows CLI backends fail through npm shims#101378
steipete merged 6 commits into
mainfrom
codex/fix-windows-cli-shims

Conversation

@steipete

@steipete steipete commented Jul 7, 2026

Copy link
Copy Markdown
Contributor

Closes #98573
Closes #92054
Closes #91489

Supersedes #98952, with contributor credit to @wendy-chsy.

What Problem This Solves

Fixes an issue where Windows users running globally installed Gemini CLI or Claude Code backends could fail to start the CLI because Node does not execute npm .cmd launchers directly.

Why This Change Was Made

Resolve standard Windows npm launchers through the existing generic spawn-program resolver, then execute their Node entrypoint or native executable directly. This keeps provider policy out of the process supervisor and preserves structured arguments, including Gemini prompts containing shell metacharacters, without opting into shell: true or cmd.exe parsing.

User Impact

Gemini CLI and Claude Code backends installed through npm now start on Windows while prompts and arguments remain intact. Existing package-manager shim handling remains unchanged when PATH probing cannot resolve a wrapper.

Evidence

  • Focused tests pass on Blacksmith Testbox through Crabbox (tbx_01kwxdx905kdbyrwcjgr2nrmnm): 21/21 child-adapter tests, 6/6 Windows-spawn tests, and 3/3 Docker-invocation sibling tests.
  • check:changed passed on the same Testbox, including tsgo, all oxlint shards, import-cycle checks, package guards, and generated-surface checks.
  • Regression fixtures use the current cmd-shim launcher shape for Gemini's JavaScript entrypoint and Claude's native executable, including a prompt with &, |, >, and %.
  • Fresh structured autoreview completed with no actionable findings.
  • Native Windows Server proof passed on AWS Crabbox cbx_4f9050b097eb, run run_4b48efb2298b, using Node 24.18.0: 4/4 targeted npm-shim and custom-wrapper tests passed.

@openclaw-barnacle openclaw-barnacle Bot added size: S maintainer Maintainer-authored PR labels Jul 7, 2026
@clawsweeper

clawsweeper Bot commented Jul 7, 2026

Copy link
Copy Markdown
Contributor

Codex review: stale review; fresh review needed.

Summary
The latest durable ClawSweeper review was for head 268e748f5d9f1ba9130024931fd13ffd829d095c, but the PR head is now 3cef0a620f2f6552da06bbfc860a01cbb9df7c8c. Its old verdict and PR readiness labels are no longer current.

Next step
Run or wait for a fresh ClawSweeper review on the current PR head.

Review history (1 earlier review cycle)
  • reviewed 2026-07-07T05:41:19.577Z sha 268e748 :: needs real behavior proof before merge. :: [P2] Preserve npm's adjacent node.exe lookup

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d6e26b699d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +39 to +42
execPath:
process.platform === "win32"
? resolveWindowsExecutablePath("node", params.env ?? process.env)
: undefined,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Resolve Node relative to the npm shim

When a Windows backend is configured as an absolute npm .cmd path (for example C:\Program Files\nodejs\gemini.cmd) and the service PATH does not include that directory, this resolves the unwrapped JS entrypoint with node searched only from params.env/process.env. npm cmd-shims first try %dp0%\node.exe, so the wrapper would still work with the adjacent Node installation, but the new direct path can fail with ENOENT or run a different Node. Preserve the shim's own adjacent-Node resolution before bypassing it.

Useful? React with 👍 / 👎.

@clawsweeper clawsweeper Bot added rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. P1 High-priority user-facing bug, regression, or broken workflow. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 availability 🚨 May cause crashes, hangs, restart loops, stalls, or process outages. labels Jul 7, 2026
@clawsweeper clawsweeper Bot removed rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 availability 🚨 May cause crashes, hangs, restart loops, stalls, or process outages. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. labels Jul 7, 2026
@steipete

steipete commented Jul 7, 2026

Copy link
Copy Markdown
Contributor Author

Land-ready at exact head 3cef0a620f2f6552da06bbfc860a01cbb9df7c8c.

  • Best-fix review: the process supervisor now delegates standard npm wrapper discovery to the generic Windows spawn owner, resolves JavaScript entrypoints through PATH's real Node executable, launches native entrypoints directly, and keeps arbitrary batch wrappers on the existing trusted cmd.exe path. This avoids provider allowlists and shell-mediated prompt parsing.
  • Contract proof: current cmd-shim launchers use the guarded find_dp0 shape covered by the resolver; Node's Windows process contract requires .cmd/.bat mediation, so direct Node/native entrypoint execution preserves structured argv without shell: true.
  • Focused proof: Blacksmith Testbox through Crabbox tbx_01kwxdx905kdbyrwcjgr2nrmnm passed 30/30 child-adapter, Windows-spawn, and Docker-invocation tests.
  • Broad proof: check:changed passed on the same Testbox, including tsgo, all oxlint shards, package guards, import-cycle checks, and generated-surface checks.
  • Native proof: AWS Crabbox cbx_4f9050b097eb, run run_4b48efb2298b, passed 4/4 targeted tests on Windows Server with Node 24.18.0; lease released.
  • Review: fresh final autoreview clean at 0.82 after the related Docker sibling path was verified and covered.
  • Exact hosted CI: run 28844574084 passed all 55 jobs (46 success, 9 skipped).

Known proof gaps: none.

@steipete
steipete merged commit 7b366e1 into main Jul 7, 2026
115 of 121 checks passed
@steipete
steipete deleted the codex/fix-windows-cli-shims branch July 7, 2026 05:57
@steipete

steipete commented Jul 7, 2026

Copy link
Copy Markdown
Contributor Author

Merged via squash.

github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request Jul 7, 2026
* fix(process): resolve Windows npm CLI shims directly

Co-authored-by: wendy-chsy <[email protected]>

* docs(changelog): note Windows CLI shim fix

* docs(process): explain Windows shim boundary

* chore: keep release changelog owner-only

* test(process): isolate Windows shim resolution

* fix(process): classify Windows forwarding shims safely

---------

Co-authored-by: wendy-chsy <[email protected]>
sheyanmin pushed a commit to sheyanmin/openclaw that referenced this pull request Jul 8, 2026
* fix(process): resolve Windows npm CLI shims directly

Co-authored-by: wendy-chsy <[email protected]>

* docs(changelog): note Windows CLI shim fix

* docs(process): explain Windows shim boundary

* chore: keep release changelog owner-only

* test(process): isolate Windows shim resolution

* fix(process): classify Windows forwarding shims safely

---------

Co-authored-by: wendy-chsy <[email protected]>
giodl73-repo pushed a commit to giodl73-repo/openclaw that referenced this pull request Jul 8, 2026
* fix(process): resolve Windows npm CLI shims directly

Co-authored-by: wendy-chsy <[email protected]>

* docs(changelog): note Windows CLI shim fix

* docs(process): explain Windows shim boundary

* chore: keep release changelog owner-only

* test(process): isolate Windows shim resolution

* fix(process): classify Windows forwarding shims safely

---------

Co-authored-by: wendy-chsy <[email protected]>
wheakerd pushed a commit to wheakerd/clawdbot that referenced this pull request Jul 15, 2026
* fix(process): resolve Windows npm CLI shims directly

Co-authored-by: wendy-chsy <[email protected]>

* docs(changelog): note Windows CLI shim fix

* docs(process): explain Windows shim boundary

* chore: keep release changelog owner-only

* test(process): isolate Windows shim resolution

* fix(process): classify Windows forwarding shims safely

---------

Co-authored-by: wendy-chsy <[email protected]>
(cherry picked from commit 7b366e1)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

maintainer Maintainer-authored PR P1 High-priority user-facing bug, regression, or broken workflow. size: S

Projects

None yet

1 participant