PR #60480: fix: implement Windows stale gateway process cleanup before restart

• Repository: openclaw/openclaw
• Author: arifahmedjoy
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/60480

Description (problem / solution / changelog)

Summary

Fixes #60878

findGatewayPidsOnPortSync() in src/infra/restart-stale-pids.ts returned [] immediately on Windows (process.platform === 'win32'), causing cleanStaleGatewayProcessesSync() to silently skip killing old gateway processes during self-restart via the schtasks supervisor path (triggerOpenClawRestart).

This caused an infinite retry loop on Windows:

[gateway] already running under schtasks; waiting 5000ms before retrying startup

The new gateway instance could never bind port 18789 because the old process was never terminated.

Root Cause

The self-restart path on Windows (triggerOpenClawRestart -> relaunchGatewayScheduledTask) calls cleanStaleGatewayProcessesSync() before spawning the schtasks restart script. But since findGatewayPidsOnPortSync returns [] on Windows, no stale processes are ever found or killed. The new schtasks-launched gateway then races the old one for the port and enters an unbounded retry loop.

Note: openclaw daemon restart works correctly because it uses the restartScheduledTask() path in service.ts, which properly calls terminateScheduledTaskGatewayListeners() with the Windows-aware findVerifiedGatewayListenerPidsOnPortSync(). Only the in-process self-restart path was broken.

Changes

New: src/infra/windows-port-pids.ts

Extracted all Windows-specific port scanning and process-args helpers from gateway-processes.ts into a shared module with configurable timeoutMs parameter. This:

• Breaks the circular import between restart-stale-pids.ts and gateway-processes.ts (both now import from windows-port-pids.ts instead of from each other)
• Fixes poll budget overshoot: Windows poll calls use POLL_SPAWN_TIMEOUT_MS (400ms) instead of the 5000ms default, keeping each poll within the waitForPortFreeSync 2s budget

src/infra/restart-stale-pids.ts

• findGatewayPidsOnPortSync: On win32, discovers listening PIDs via readWindowsListeningPidsOnPortSync + verifies each with readWindowsProcessArgsSync / isGatewayArgv
• pollPortOnceWindows: Uses readWindowsListeningPidsOnPortSync(port, 400) — just checks if port has any listener, no verification needed (stale gateway already killed)
• terminateStaleProcessesSync: Add terminateStaleProcessesWindows() using taskkill.exe (graceful /T first, then /F force-kill) instead of SIGTERM/SIGKILL

src/infra/gateway-processes.ts

• Delegates Windows helpers to the new windows-port-pids.ts module
• Removes ~100 lines of inlined Windows functions
• Keeps findVerifiedGatewayListenerPidsOnPortSync public API unchanged

src/infra/restart-stale-pids.test.ts

• Mocks windows-port-pids.js (port scanning + process args) for the win32 platform-mock tests
• Updated win32 tests verify delegation to readWindowsListeningPidsOnPortSync and readWindowsProcessArgsSync
• Tests use real isGatewayArgv for full integration coverage

Testing

• Lightly tested: verified fix resolves the infinite restart loop on Windows 11
• Confirmed openclaw daemon restart and openclaw gateway call health work after fix
• Existing Unix tests unaffected — all 38 restart-stale-pids tests pass
• All 6 gateway-processes tests pass after refactor
• Updated test mocks verify win32 delegation with real isGatewayArgv validation

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/infra/gateway-processes.ts (modified, +5/-108)
• src/infra/restart-stale-pids.test.ts (modified, +262/-9)
• src/infra/restart-stale-pids.ts (modified, +151/-3)
• src/infra/windows-port-pids.ts (added, +151/-0)