fix: Windows self-update restart fails due to os.execv behavior

[jja881]

Problem

On Windows, does NOT replace the current process - it spawns a new process while the old one keeps running. This causes:

1. Old process continues holding the port (8787)
2. New process fails to bind the same port ()
3. WebUI shows 'Update failed' after 15-second timeout

Solution

On Windows (), use with flag to start the new process, then to terminate the old one and release the port.

This matches the behavior on Linux where properly replaces the process image.

Testing

Tested on Windows 10 with Python 3.11. Self-update now successfully restarts the WebUI.

[greptile-apps]

Greptile Summary

This PR fixes the Windows self-update restart failure caused by os.execv() not replacing the process image on Windows, and bundles the sprint-29 security hardening for CSRF forwarded-host and TTS forwarded-IP/prosody validation that shipped alongside it.

• Windows restart (api/updates.py, server.py): On win32, the restart now uses subprocess.Popen with DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP and all stdio redirected to DEVNULL, then calls os._exit(0) immediately so the old process releases the port. server.py adds a 10 s bind-retry loop using SO_EXCLUSIVEADDRUSE to tolerate the brief OS socket-teardown window. Previously flagged issues (1 s sleep before exit, inherited file handles) are both addressed.
• CSRF hardening (api/routes.py): X-Forwarded-Host / X-Real-Host are no longer trusted by default in the same-origin check; they require HERMES_WEBUI_TRUST_FORWARDED_HOST=1. Existing reverse-proxy tests updated accordingly.
• TTS security (api/routes.py): Rate-limit bucket now keys on the real client IP by default (X-Forwarded-For trusted only via HERMES_WEBUI_TRUST_FORWARDED_FOR=1); rate and pitch prosody values are validated against ±N% / ±NHz grammar before being passed to edge_tts.Communicate.

Confidence Score: 5/5

Safe to merge; the Windows restart path is well-constructed and the previously flagged broken-pipe and port-hold issues are both resolved.

The core Windows restart change (subprocess.Popen + os._exit(0), DEVNULL streams, bind-retry loop) is correct and addresses all previously raised concerns. The bundled security changes are guarded by explicit env-var opt-ins and have matching test coverage. The only gap is a missing CHANGELOG entry for the Windows fix itself.

CHANGELOG.md is missing a Fixed entry for the Windows self-update restart fix; all code files look correct.

Important Files Changed

Filename	Overview
api/updates.py	Windows restart path replaced: uses subprocess.Popen with DETACHED_PROCESS + CREATE_NEW_PROCESS_GROUP and DEVNULL streams, then os._exit(0) to release the port immediately. Previous issues (sleep before exit, inherited file handles) are fully addressed.
server.py	Added SO_EXCLUSIVEADDRUSE bind-retry loop on Windows (20 × 0.5 s = 10 s window) to tolerate the brief port-teardown period after the old process calls os._exit(0). time is already imported; allow_reuse_address=False prevents SO_REUSEADDR from conflicting with SO_EXCLUSIVEADDRUSE on retry iterations.
api/routes.py	CSRF check now only trusts X-Forwarded-Host under explicit opt-in env var; TTS rate limiter likewise opts in to X-Forwarded-For; new _normalize_tts_prosody validates rate/pitch against ±N%/±NHz grammar before passing to edge_tts.
CHANGELOG.md	Adds v0.51.267 Security section for CSRF/TTS hardening, but omits a Fixed entry for the Windows self-update restart fix that is the stated subject of this PR.
tests/test_issue2931_edge_tts_endpoint.py	New tests cover: prosody validation rejects injected markup and out-of-range values, valid prosody round-trips to edge_tts kwargs, and rate-limit bucket uses real client IP by default with forwarded-for opt-in path also tested.
tests/test_issue1909_csrf_token.py	Adds test confirming X-Forwarded-Host is ignored without opt-in env var; updates existing reverse-proxy test to set the opt-in flag it now requires.
tests/test_issue3635_profile_chip_active.py	Adds a standing cross-file invariant guard ensuring the profile chip (ui.js) and dropdown active-row (panels.js) always read S.activeProfile as the same source of truth.
tests/test_sprint29.py	Updates forwarded-host CSRF port-normalization tests to set the HERMES_WEBUI_TRUST_FORWARDED_HOST opt-in flag, which is now required for X-Forwarded-Host to participate in the origin check.

Sequence Diagram

sequenceDiagram
    participant OldProcess as Old Process (Windows)
    participant OS as Windows OS
    participant NewProcess as New Process

    OldProcess->>OldProcess: self-update triggered
    OldProcess->>NewProcess: "subprocess.Popen(args, DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP, stdio=DEVNULL)"
    OldProcess->>OS: os._exit(0)
    OS-->>OS: socket teardown begins (port released)
    NewProcess->>NewProcess: Python interpreter + imports start
    loop Retry up to 20× (0.5 s each)
        NewProcess->>OS: socket.bind(port 8787) with SO_EXCLUSIVEADDRUSE
        alt Port still releasing
            OS-->>NewProcess: WSAEADDRINUSE (10048)
            NewProcess->>NewProcess: time.sleep(0.5)
        else Port free
            OS-->>NewProcess: bind() success
            NewProcess->>NewProcess: serve_forever()
        end
    end

Loading

_{Reviews (3): Last reviewed commit: "fix: add bind retry loop on Windows to h..." | Re-trigger Greptile}

[nesquena-hermes]

Read the api/updates.py change against _schedule_restart on master (1048-1083) and, importantly, the Windows bind path in server.py. The diagnosis is right — os.execv on Windows spawns rather than replaces, so the old process lingers — but the proposed Popen-then-os._exit ordering collides with how this server binds its port on Windows, and I think it'll fail the same way the bug it's fixing does.

(Heads up on the diff: the origin/master...HEAD range also shows the v0.51.267 CSRF/TTS work because the branch re-created those release commits with new SHAs on top of a v0.51.266 base — fd2e2868 vs master's merged f1211e1f for the same #3648. The only novel change here is the api/updates.py Windows branch; the CSRF/TTS/profile-chip files are already on master. A rebase onto current origin/master will shrink this to the one file.)

The ordering races against SO_EXCLUSIVEADDRUSE

server.py:208-213 deliberately binds with exclusive-use on Windows:

def server_bind(self):
    if sys.platform == 'win32':
        self.allow_reuse_address = False
        SO_EXCLUSIVEADDRUSE = getattr(socket, 'SO_EXCLUSIVEADDRUSE', -5)
        self.socket.setsockopt(socket.SOL_SOCKET, SO_EXCLUSIVEADDRUSE, 1)
    super().server_bind()

The PR spawns the replacement before the parent releases the socket:

subprocess.Popen(args, ...)   # child starts, races to bind()
os._exit(0)                    # parent only now releases the port

With SO_EXCLUSIVEADDRUSE, the OS refuses a second bind to that port while the parent still holds it. The child will typically reach bind() within milliseconds — well before the parent's interpreter tears down and the kernel reclaims the socket — so the child hits "address already in use" and dies. That's the exact failure the PR is trying to eliminate, just moved from execv to Popen. On a fast machine this will reproduce reliably.

Two ways to make it robust

Option A — parent exits first, then a tiny launcher spawns the child. Order it so the port is provably free before the new process tries to bind. A small detached relauncher (e.g. cmd /c "timeout /t 1 >nul & <python> server.py"), or having the child retry bind() with backoff, both close the window. A bind retry in server.py is the most defensive — it'd help any restart path, not just Windows self-update.

Option B — child waits for the port. Have the spawned process poll /health (or attempt-and-retry the bind) until the parent is gone. This mirrors the client-side _waitForServerThenReload readiness contract that PR #3654 is adding; the two are complementary — #3654 keeps the browser from reloading early, this would keep the new server from binding early.

Option A with a bind() retry loop is my recommendation since it's the smallest change that's correct regardless of timing.

Lock interaction is fine

os._exit(0) inside with _apply_lock: (1049) skips normal lock release, but that's harmless here — the process is dying, the OS reclaims everything, and master already relies on the same "threads die when the process image is replaced" property for os.execv. No deadlock concern.

Test gap

The novel change has no Windows-specific coverage (understandably hard to exercise in CI). At minimum, a unit test that monkeypatches sys.platform = 'win32' and asserts _schedule_restart calls subprocess.Popen with DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP (and does not call os.execv) would lock in the platform branch. The bind-race itself is timing-dependent, so the retry loop from Option A is what actually needs the integration coverage — worth a note in the PR that it was manually verified on the overlap window, not just a single happy-path restart.

Solid root-cause analysis; the fix just needs the bind ordering sorted before it'll hold on fast Windows hosts.