Skip to content

fix(gateway-windows): handle non-ASCII paths and uv pythonw shim on CJK Windows - #40374

Closed
Shura0307 wants to merge 1 commit into
NousResearch:mainfrom
Shura0307:fix/gateway-non-ascii-paths
Closed

fix(gateway-windows): handle non-ASCII paths and uv pythonw shim on CJK Windows#40374
Shura0307 wants to merge 1 commit into
NousResearch:mainfrom
Shura0307:fix/gateway-non-ascii-paths

Conversation

@Shura0307

Copy link
Copy Markdown

Problem

Two bugs affect Chinese/Japanese/Korean Windows users whose home directory contains non-ASCII characters (e.g. C:\Users\银\...):

  1. .cmd file corruption_build_gateway_cmd_script() writes raw UTF-8 CJK characters into the generated .cmd file. cmd.exe on these Windows editions interprets the file using the system ANSI/OEM code page (e.g. GBK for zh-CN), which garbles the set and cd commands and silently breaks the Scheduled Task startup.

  2. Visible console window at startup_build_gateway_cmd_script() uses _derive_venv_pythonw(python_path) which returns the venv's pythonw.exe. On uv-created venvs, venv\Scripts\pythonw.exe is a shim that spawns the base interpreter python.exe (a console-mode app), opening a visible Windows Terminal window.

  3. start() gives up too early — When schtasks /Run returns exit code 0 but the gateway process does not appear within 6 seconds (common on slower machines), start() reports failure and returns without starting the gateway.

Fix

_cmd_safe_path() — new helper that replaces APPDATA/ LOCALAPPDATA prefixed paths with their environment-variable form (%APPDATA%, %LOCALAPPDATA%), keeping the generated .cmd files pure ASCII regardless of the user's home directory encoding.

uv-aware pythonw_build_gateway_cmd_script() now calls _resolve_detached_python() (the same function _spawn_detached() already uses) to get the true base pythonw.exe from the uv cache, and passes the venv site-packages via PYTHONPATH. No more window popping up.

Graceful start() fallback — When schtasks /Run succeeds but no process appears within the 6-second window, start() now falls back to _spawn_detached() instead of silently giving up.

Testing

Tested on Windows 11 Home zh-CN with username (a CJK character):

  • hermes gateway start -> gateway starts silently, no console window
  • hermes gateway restart -> clean stop + silent start
  • Generated .cmd file is pure ASCII (zero CJK characters)
  • Scheduled Task logon startup works without corruption

…hinese Windows

Two fixes for Chinese Windows users (CJK username in path):

1. _cmd_safe_path(): replace APPDATA/LOCALAPPDATA paths with %APPDATA%/
   %LOCALAPPDATA% env vars so generated .cmd files stay pure ASCII.
   cmd.exe on Chinese Windows chokes on UTF-8 CJK characters in batch
   files, breaking the set and cd commands.

2. uv-resolved pythonw in .cmd generation: uv venv's pythonw.exe is a
   shim that spawns the base python.exe (console app), which opens a
   visible Windows Terminal tab. Use _resolve_detached_python() in
   _build_gateway_cmd_script() so the generated .cmd uses the base
   pythonw.exe directly + passes venv site-packages via PYTHONPATH.

3. start() fallback: when schtasks /Run returns code 0 but no gateway
   process appears within 6s (common on Windows with slow task startup),
   fall back to _spawn_detached() instead of giving up.
@alt-glitch alt-glitch added type/bug Something isn't working comp/gateway Gateway runner, session dispatch, delivery platform/telegram Telegram bot adapter area/config Config system, migrations, profiles P2 Medium — degraded but workaround exists labels Jun 6, 2026
@teknium1

Copy link
Copy Markdown
Contributor

Thanks for documenting the localized Windows and uv-launcher failure modes. This is an automated hermes-sweeper review; current main now provides the requested behavior through a later, different launcher design.

  • hermes_cli/gateway_windows.py:659-663 creates Scheduled Tasks for wscript.exe and the generated .vbs launcher, rather than executing the raw .cmd wrapper; the Startup fallback follows the same VBS route (hermes_cli/gateway_windows.py:549-556).
  • The uv workaround is already in the shared launch path: _build_gateway_cmd_script() calls _resolve_detached_python() (hermes_cli/gateway_windows.py:404), which selects base pythonw.exe and supplies venv site-packages for uv environments (hermes_cli/gateway_windows.py:734-756). Regression coverage is present at tests/hermes_cli/test_gateway_windows.py:213-245.
  • start() now directly calls _spawn_detached() (hermes_cli/gateway_windows.py:1460-1490), so it no longer relies on schtasks /Run or its readiness wait. This was introduced by e7d2f0b93ca29b2cd95d6623fe8af7646173a75b; the Scheduled Task VBS migration shipped in 433db17c0a8d5581b4fb38289539fc1ee5cc7696.

The timeline’s related PR #41028 reports the same uv shim behavior; main now contains the corresponding production handling and test coverage. Closing as implemented on main.

@teknium1 teknium1 closed this Jul 14, 2026
@teknium1 teknium1 added the sweeper:implemented-on-main Sweeper: behavior already present on current main label Jul 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/config Config system, migrations, profiles comp/gateway Gateway runner, session dispatch, delivery P2 Medium — degraded but workaround exists platform/telegram Telegram bot adapter sweeper:implemented-on-main Sweeper: behavior already present on current main type/bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants