fix(update): migrate legacy pythonw Windows gateway launchers to the hidden-console design

Two halves close the 'legacy pythonw gateways survive updates forever' gap:

1. hermes update now regenerates the installed Scheduled Task / Startup
   launcher scripts (gateway.cmd + gateway.vbs) during the gateway resume
   phase. They are persistence artifacts written once at install time;
   updates never touched them, so pre-aa2ae36c3f installs kept launching
   the gateway through pythonw.exe forever — every descendant spawn
   flashed a conhost (#54220/#56747) and, since #70344, the console-less
   gateway died at startup with RuntimeError: sys.stderr is None (#71671).
   The task /TR points at a stable script path, so rewriting the files
   retargets it with no schtasks call and no UAC. No-op for modern
   installs; best-effort so a failed refresh never fails the update.

2. _resolve_detached_python() normalizes a legacy pythonw.exe interpreter
   to its sibling console python.exe when it exists, so the update
   pause/resume argv-replay path (and any other caller handed a legacy
   command line) respawns on the current design instead of faithfully
   resurrecting the old one. Keeps pythonw when no sibling exists — a
   failed respawn is worse than a console-less gateway.

hermes_cli/gateway_windows.py

@@ -744,8 +744,26 @@ def _resolve_detached_python(python_exe: str) -> tuple[str, Path, list[str]]:
     ``extra_pythonpath`` is always empty now; the tuple shape is kept so the
     call sites (argv builders, cmd/vbs renderers, restart-spec rewriter,
     gateway watcher) stay unchanged.
+
+    Legacy normalization: launchers and argv snapshots from pre-aa2ae36c3f
+    installs lead with ``pythonw.exe``. When the sibling console
+    ``python.exe`` exists, swap to it so respawns and regenerated launchers
+    get the hidden-console design instead of resurrecting the console-less
+    daemon (the #54220/#56747 flash class, plus the ``sys.stderr is None``
+    startup-crash class from #71671).
     """
     p = Path(python_exe)
+    if p.name.lower() in ("pythonw.exe", "pythonw"):
+        sibling = p.with_name("python.exe" if p.suffix else "python")
+        try:
+            if sibling.exists():
+                p = sibling
+                python_exe = str(sibling)
+        except OSError:
+            # Can't stat the sibling — keep the original interpreter. A
+            # console-less gateway is worse than a hidden-console one, but a
+            # failed respawn is worse still.
+            pass
     venv_dir = p.parent.parent
     return (python_exe, venv_dir, [])
 

hermes_cli/main.py

@@ -11425,6 +11425,36 @@ def _warn_incomplete_gateway_fleet_restart(failed_units: list) -> None:
     print("    sudo systemctl restart <unit>     # system-scope")
 
 
+def _refresh_windows_gateway_launchers() -> None:
+    """Regenerate installed Windows gateway launcher scripts after update.
+
+    The Scheduled Task / Startup-folder launchers (``gateway.cmd`` +
+    ``gateway.vbs``) are persistence artifacts written once at install time —
+    ``hermes update`` never touched them, so installs created before the
+    hidden-console rework (aa2ae36c3f) kept launching the gateway through
+    ``pythonw.exe`` forever: every descendant spawn flashed a conhost
+    (#54220/#56747) and, since #70344, the console-less gateway died at
+    startup with ``RuntimeError: sys.stderr is None`` (#71671).
+
+    The task's /TR points at a stable script path, so rewriting the files in
+    place retargets the task without any schtasks call (no UAC needed).
+    ``_write_task_script`` is idempotent and renders from current code, so
+    this is a no-op for modern installs. Best-effort: a failed refresh must
+    never fail the update.
+    """
+    if not _is_windows():
+        return
+    try:
+        from hermes_cli import gateway_windows
+
+        if not gateway_windows.is_installed():
+            return
+        gateway_windows._write_task_script()
+        print("  ✓ Refreshed Windows gateway launcher scripts")
+    except Exception as exc:
+        logger.debug("Could not refresh Windows gateway launchers after update: %s", exc)
+
+
 def _resume_windows_gateways_after_update(token: dict | None) -> None:
     """Restart Windows profile gateways previously paused for update."""
     if not token or not token.get("resume_needed"):
@@ -11433,6 +11463,11 @@ def _resume_windows_gateways_after_update(token: dict | None) -> None:
     if not _is_windows():
         return
 
+    # Regenerate the persisted launcher scripts before respawning anything,
+    # so a legacy pythonw-era Scheduled Task / Startup entry comes back on
+    # the current hidden-console design at the next login too.
+    _refresh_windows_gateway_launchers()
+
     profiles = token.get("profiles") or {}
     unmapped = token.get("unmapped") or []
     cold_start = bool(token.get("cold_start_if_installed"))

tests/hermes_cli/test_update_gateway_launcher_refresh.py

@@ -0,0 +1,170 @@
+"""Legacy pythonw launcher normalization + post-update launcher refresh.
+
+Covers the two halves of the "legacy pythonw gateways survive updates
+forever" gap:
+
+1. ``gateway_windows._resolve_detached_python`` — normalizes a legacy
+   ``pythonw.exe`` interpreter (pre-aa2ae36c3f launchers / argv snapshots)
+   to the sibling console ``python.exe`` so respawns and regenerated
+   launchers use the hidden-console design (#54220/#56747) and don't die
+   with ``RuntimeError: sys.stderr is None`` (#71671).
+2. ``hermes_cli.main._refresh_windows_gateway_launchers`` — ``hermes
+   update`` regenerates the installed Scheduled Task / Startup launcher
+   scripts instead of leaving install-time artifacts stale forever.
+
+Windows-specific paths are exercised via ``_is_windows`` patching so they
+run on any host (same approach as test_update_venv_health).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest import mock
+
+import hermes_cli.gateway_windows as gateway_windows
+import hermes_cli.main as cli_main
+
+
+# ---------------------------------------------------------------------------
+# _resolve_detached_python: legacy pythonw normalization
+# ---------------------------------------------------------------------------
+
+
+def _make_venv(tmp_path: Path, *, with_console_python: bool) -> tuple[Path, Path]:
+    scripts = tmp_path / "venv" / "Scripts"
+    scripts.mkdir(parents=True)
+    pythonw = scripts / "pythonw.exe"
+    pythonw.write_text("", encoding="utf-8")
+    python = scripts / "python.exe"
+    if with_console_python:
+        python.write_text("", encoding="utf-8")
+    return pythonw, python
+
+
+def test_resolve_detached_python_swaps_legacy_pythonw_for_console_sibling(tmp_path):
+    pythonw, python = _make_venv(tmp_path, with_console_python=True)
+
+    exe, venv_dir, extra = gateway_windows._resolve_detached_python(str(pythonw))
+
+    assert exe == str(python)
+    assert venv_dir == tmp_path / "venv"
+    assert extra == []
+
+
+def test_resolve_detached_python_keeps_pythonw_when_no_console_sibling(tmp_path):
+    """A failed respawn is worse than a console-less gateway — never swap to
+    an interpreter that doesn't exist."""
+    pythonw, _python = _make_venv(tmp_path, with_console_python=False)
+
+    exe, venv_dir, extra = gateway_windows._resolve_detached_python(str(pythonw))
+
+    assert exe == str(pythonw)
+    assert venv_dir == tmp_path / "venv"
+    assert extra == []
+
+
+def test_resolve_detached_python_leaves_console_python_untouched(tmp_path):
+    _pythonw, python = _make_venv(tmp_path, with_console_python=True)
+
+    exe, venv_dir, _extra = gateway_windows._resolve_detached_python(str(python))
+
+    assert exe == str(python)
+    assert venv_dir == tmp_path / "venv"
+
+
+def test_restart_spec_normalizes_legacy_pythonw_argv(tmp_path):
+    """A pre-rework Scheduled Task argv snapshot (leading pythonw.exe) must be
+    respawned through the console python + hidden-console launch, with every
+    argument after the interpreter preserved verbatim."""
+    pythonw, python = _make_venv(tmp_path, with_console_python=True)
+
+    # Pre-import so the function's lazy imports resolve from sys.modules
+    # instead of re-importing under the win32 platform patch (see the
+    # TestWindowlessGatewayRestartSpec comment in
+    # tests/tools/test_windows_native_support.py).
+    import hermes_cli.config  # noqa: F401
+    import hermes_cli.gateway  # noqa: F401
+
+    argv = [str(pythonw), "-m", "hermes_cli.main", "gateway", "run"]
+    with mock.patch.object(gateway_windows.sys, "platform", "win32"), mock.patch.object(
+        gateway_windows, "_stable_gateway_working_dir", return_value=str(tmp_path)
+    ), mock.patch("hermes_cli.config.get_hermes_home", return_value=str(tmp_path)):
+        new_argv, cwd, env = gateway_windows.windowless_gateway_restart_spec(list(argv))
+
+    assert new_argv[0] == str(python)
+    assert new_argv[1:] == argv[1:]
+    assert cwd == str(tmp_path)
+    assert env["VIRTUAL_ENV"] == str(tmp_path / "venv")
+
+
+# ---------------------------------------------------------------------------
+# _refresh_windows_gateway_launchers: hermes update regenerates launchers
+# ---------------------------------------------------------------------------
+
+
+def test_refresh_is_noop_off_windows():
+    with mock.patch.object(cli_main, "_is_windows", return_value=False), mock.patch.object(
+        gateway_windows, "is_installed"
+    ) as is_installed:
+        cli_main._refresh_windows_gateway_launchers()
+    is_installed.assert_not_called()
+
+
+@mock.patch.object(cli_main, "_is_windows", return_value=True)
+def test_refresh_rewrites_launchers_when_installed(_winp):
+    with mock.patch.object(gateway_windows, "is_installed", return_value=True), mock.patch.object(
+        gateway_windows, "_write_task_script"
+    ) as write_script:
+        cli_main._refresh_windows_gateway_launchers()
+    write_script.assert_called_once_with()
+
+
+@mock.patch.object(cli_main, "_is_windows", return_value=True)
+def test_refresh_skips_when_no_autostart_installed(_winp):
+    with mock.patch.object(gateway_windows, "is_installed", return_value=False), mock.patch.object(
+        gateway_windows, "_write_task_script"
+    ) as write_script:
+        cli_main._refresh_windows_gateway_launchers()
+    write_script.assert_not_called()
+
+
+@mock.patch.object(cli_main, "_is_windows", return_value=True)
+def test_refresh_failure_never_raises(_winp):
+    with mock.patch.object(gateway_windows, "is_installed", return_value=True), mock.patch.object(
+        gateway_windows, "_write_task_script", side_effect=OSError("locked")
+    ):
+        cli_main._refresh_windows_gateway_launchers()  # must not raise
+
+
+@mock.patch.object(cli_main, "_is_windows", return_value=True)
+def test_resume_after_update_refreshes_launchers_first(_winp):
+    """The resume path regenerates launchers before any respawn, including the
+    cold-start-only shape (no gateway was running, autostart installed)."""
+    calls: list[str] = []
+    with mock.patch.object(
+        cli_main,
+        "_refresh_windows_gateway_launchers",
+        side_effect=lambda: calls.append("refresh"),
+    ), mock.patch.object(
+        cli_main,
+        "_cold_start_windows_gateway_after_update",
+        side_effect=lambda: calls.append("cold_start"),
+    ):
+        cli_main._resume_windows_gateways_after_update(
+            {
+                "resume_needed": True,
+                "profiles": {},
+                "unmapped_pids": [],
+                "unmapped": [],
+                "cold_start_if_installed": True,
+            }
+        )
+
+    assert calls == ["refresh", "cold_start"]
+
+
+def test_resume_after_update_noop_token_skips_refresh():
+    with mock.patch.object(cli_main, "_refresh_windows_gateway_launchers") as refresh:
+        cli_main._resume_windows_gateways_after_update(None)
+        cli_main._resume_windows_gateways_after_update({"resume_needed": False})
+    refresh.assert_not_called()