fix(update): coordinate Windows gateway pause across three layers during desktop update (#74386)

[webtecnica]

Summary

Fixes #74386 — on Windows gateway-enabled installs, the desktop Update button triggers a three-layer chain (Electron → Rust bootstrapper → Python CLI) where each layer has a different gap in gateway process coordination, guaranteeing that the desktop updater can never complete on a gateway-enabled install without manual hermes gateway stop intervention.

Changes

Layer 1 — Electron (apps/desktop/electron/main.ts)

Add pauseWindowsGatewaysForUpdate / resumeWindowsGatewaysAfterUpdate functions that run the Python _gateway_update_lock subprocess bridge to pause gateways before the venv-blocker scan. The pre-flight blocker scan was finding the running gateway and aborting before the CLI updater even started.

The resume token is passed to the spawned CLI updater via HERMES_WINDOWS_GATEWAY_RESUME_TOKEN env var so it does not double-pause. On error paths (blocked/probe-failure), gateways are resumed before the UI shows the error.

Layer 2 — Fallback

stopVenvBlockers in venv-blocker-scan.ts provides a TypeScript-side fallback: when the blocker scan finds processes, isGatewayProcess() classifies them by cmdline, and gateway PIDs are force-killed via taskkill /F before re-scanning. Non-gateway processes are still reported as blockers.

Layer 3 — Python CLI (hermes_cli/update_cmd.py, hermes_cli/_gateway_update_lock.py)

Two fixes:

1. Env-var token passthrough: Before calling _pause_windows_gateways_for_update(), check HERMES_WINDOWS_GATEWAY_RESUME_TOKEN. When set by the Electron preflight, use the Electron's token as the resume token (skip re-pause — gateways are already gone) but still register the atexit resume handler.

2. Graceful gateway handling in venv-holder check: When _detect_venv_python_processes() finds remaining holders after gateway pause, classify each by cmdline. If all are gateways (e.g. gateways spawned via --replace or shim-wrapped children that find_gateway_pids() missed), force-kill them with terminate_pid(force=True) and proceed instead of aborting. Only abort when a non-gateway holder (the Desktop backend) remains.

New module: hermes_cli/_gateway_update_lock.py

Subprocess-callable bridge invoked by Electron:

• python -m hermes_cli._gateway_update_lock pause — calls _pause_windows_gateways_for_update(), prints JSON resume token
• python -m hermes_cli._gateway_update_lock resume <json-token> — calls _resume_windows_gateways_after_update()

Files changed

File	Change
apps/desktop/electron/main.ts	+Layer 1: gateway pause/resume helpers, integrated into applyUpdates preflight
apps/desktop/electron/venv-blocker-scan.ts	+isGatewayProcess + stopVenvBlockers helpers
apps/desktop/electron/venv-blocker-scan.test.ts	+tests for new helpers
hermes_cli/_gateway_update_lock.py	+new module: subprocess bridge for pause/resume
hermes_cli/update_cmd.py	+Layer 3: env-var token passthrough + graceful gateway handling

Related

• Windows: desktop Update button can never succeed on gateway-enabled installs (venv-blocker preflight aborts on the always-running gateway) #74326 (same scenario, earlier approach)
• Windows: bootstrap-installer kills Gateway without respawning — Telegram bot silently stops responding #50090 (unmapped gateway restart after update)
• Windows: Desktop self-update can never succeed — applyUpdates' own SIGTERM triggers a renderer reconnect that respawns the backend before scanVenvBlockers runs #73822 (update-in-progress gate)

[apoapostolov]

Thanks for picking this up @webtecnica — I filed #74386 and walked the three-layer chain on a live gateway-enabled Windows install. This PR hits the right shape: Electron pre-pause before scanVenvBlockers, token handoff so CLI does not double-pause, and a second-line kill for gateways the PID-file pause missed.

I read the full diff. A few notes from that path:

Resume token drop on the taskkill path (real regression risk)

In applyUpdates, when the first scan is still blocked, stopVenvBlockers clears the rest, and the re-scan is clear, the code sets noGatewayResumeNeeded = true and then withholds HERMES_WINDOWS_GATEWAY_RESUME_TOKEN from the spawned updater.

That is wrong when pauseWindowsGatewaysForUpdate already returned a useful token. Pause snapshots profile PIDs / unmapped argv / cold_start_if_installed so resume can bring gateways back. Force-killing a leftover gateway does not mean "nothing to resume" — it means "extra PIDs that were not in the registry are gone." Dropping the token leaves the profiles that were paused permanently down until the user runs hermes gateway start or logs in again.

Suggested rule: if gatewayToken is non-null (and not a useless empty object), always pass it to the CLI, even after the taskkill fallback. Only skip the env var when there was never a resume-worthy token.

Classification mismatch (minor)

Electron uses cmdline.includes("gateway run"). Layer 3 CLI uses "gateway" in cmdline.lower(). Prefer the same marker on both sides so a process cannot be "gateway" for one layer and "real blocker" for the other.

Empty / no-gateway token from the bridge

_gateway_update_lock pause emits {"ok": true, "token": {}} when the helper returns None. JSON.stringify({}) is truthy, so CLI may treat that as _gateway_was_pre_paused with an empty dict. Resume already no-ops when resume_needed is missing, so it is mostly harmless, but Electron could treat "ok + empty/missing resume fields" as null and not set the env var. That keeps CLI's own pause path for the no-gateway case.

Heavy import on the preflight path

The bridge imports _pause_windows_gateways_for_update from hermes_cli.main. That import is not free on Windows. Related work in #74599 is shrinking venv-scan cost under Desktop's ~15s preflight budget. Worth keeping an eye on total preflight time (pause subprocess + scan) so we do not trade "always blocked on gateway" for "probe timeout / exit -1". Importing the helpers from the lighter update_cmd surface (or a thin module that does not pull full CLI) would help if preflight starts flirting with the timeout again.

Layer 2 (Rust bootstrapper)

Issue also called out force_kill_other_hermes only taskkilling hermes.exe and missing pythonw gateway. This PR hardens Electron + CLI; the bootstrapper gap is still open if something still enters that path. Fine to land Electron/CLI first — just flagging so #74386 is not closed as fully done until that path is either covered or explicitly out of scope.

Happy to re-test on the same Windows gateway install once the resume-token handoff is tightened. Appreciate the thoroughness.

[webtecnica]

Thanks for the thorough review @apoapostolov! Addressed all 4 points in 3d9d05a:

1. Resume token (🔴 regression risk) — FIXED
Removed noGatewayResumeNeeded = true on the taskkill path. The token is now ALWAYS passed to the CLI even after stopVenvBlockers. Resume already no-ops when there's nothing to do, so this is safe.

2. Classification mismatch (🟡 minor) — FIXED
Changed GATEWAY_CMDLINE_MARKER from 'gateway run' to 'gateway' in venv-blocker-scan.ts, matching the Python CLI's \"gateway\" in low check. Both sides now use the same marker.

3. Empty token (🟢 harmless) — FIXED
_gateway_update_lock no longer returns {} for the no-gateway case. Electron now checks Object.keys(t).length > 0 before treating the token as valid.

4. Heavy import (🟡 perf) — FIXED
Python bridge now imports directly from hermes_cli.update_cmd instead of hermes_cli.main, avoiding the full CLI module load on the preflight path.

Happy to iterate if anything needs tightening further!

[teknium1]

Thanks for tracing the Electron and CLI sides of this Windows update failure. The underlying premise is still present on current main: apps/desktop/electron/main.ts:2936-2945 aborts any blocked venv scan, and hermes_cli/update_cmd.py:3128-3132 aborts any remaining holder after pause.

Problems

• apps/desktop/electron/main.ts:2754 fails the required desktop lint check because the new untyped Promise is inferred as {}, so stdout is not a valid property.
• apps/desktop/electron/venv-blocker-scan.ts:236 treats any command line containing gateway as killable. The added test at venv-blocker-scan.test.ts:250 demonstrates the mismatch: git log --grep=gateway is expected to be non-gateway but is classified true in CI.

Suggested changes

• Give the pause subprocess Promise a concrete { stdout: string } result type (or use a typed promisified API).
• Parse a Hermes gateway invocation rather than using a free-text substring, and retain coverage for arguments that merely mention gateway.
• Add coverage for the Python pre-paused-token and mixed-holder paths. The current Rust fallback remains limited to hermes.exe at apps/bootstrap-installer/src-tauri/src/update.rs:738-758; scope or cover that residual path explicitly.

Automated hermes-sweeper review.

[teknium1]

This untyped Promise is inferred as Promise<{}>, so destructuring stdout fails the required desktop lint check. Give the resolved payload an explicit { stdout: string } type or use a typed promisified execFile result.

[teknium1]

A free-text gateway match is too broad for a force-kill decision: it makes the added git log --grep=gateway test fail in CI and can match non-gateway command arguments. Parse/validate the Hermes gateway invocation instead.

[teknium1]

Closing in favor of #74618, which we're salvaging for the Windows gateway-pause dead-end (#74326/#74386).

The Electron-side pre-pause can't reach already-bricked installs (it ships via the very updater that's broken), the desktop typecheck was failing, and the loose gateway substring marker misclassifies innocent commands — adding a third gateway matcher in TS is the same matcher-drift class that caused the original bug. #74618 fixes the preflight veto in repo Python the existing build invokes fresh on every scan, sharing one canonical matcher (gateway.status.looks_like_gateway_command_line).

Appreciate the deep three-layer analysis — it maps the coordination problem better than the issue itself did.

[apoapostolov]

Makes sense — thanks for the clear call.

The “already-bricked install” constraint is the decider: anything that only lands after a successful desktop rebuild cannot unstick the path that is currently broken. Putting the preflight exemption + single canonical matcher in repo Python (looks_like_gateway_command_line) so the existing Electron build picks it up on the next scan is the right cut.

I’ll watch #74618 for #74386 / #74326. Appreciate you and @iso2kx pushing the CLI-side salvage rather than stacking another TS matcher.