Skip to content

Personal AI, On Personal Devices

Python

fix(cli): make daemon/mine process management cross-platform (Windows) (#657)

antonio coutinho coutinhocf5f7cff53b0
diff --git a/src/openjarvis/cli/daemon_cmd.py b/src/openjarvis/cli/daemon_cmd.py
index 7da3c130..c2511681 100644
--- a/src/openjarvis/cli/daemon_cmd.py
+++ b/src/openjarvis/cli/daemon_cmd.py
@@ -2,8 +2,6 @@
from __future__ import annotations
-import os
-import signal
import subprocess
import sys
import time
@@ -12,6 +10,7 @@ import click
from rich.console import Console
from openjarvis.core.config import DEFAULT_CONFIG_DIR, load_config
+from openjarvis.core.utils import process_alive, terminate_process
_PID_FILE = DEFAULT_CONFIG_DIR / "server.pid"
_LOG_FILE = DEFAULT_CONFIG_DIR / "server.log"
@@ -19,47 +18,7 @@ _LOG_FILE = DEFAULT_CONFIG_DIR / "server.log"
def _pid_alive(pid: int) -> bool:
"""Return whether *pid* identifies a running process without signaling it."""
- if pid <= 0:
- return False
-
- if os.name == "nt":
- import ctypes
- from ctypes import wintypes
-
- error_invalid_parameter = 87
- synchronize = 0x00100000
- wait_object_0 = 0x00000000
-
- kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
- kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
- kernel32.OpenProcess.restype = wintypes.HANDLE
- kernel32.WaitForSingleObject.argtypes = [wintypes.HANDLE, wintypes.DWORD]
- kernel32.WaitForSingleObject.restype = wintypes.DWORD
- kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
- kernel32.CloseHandle.restype = wintypes.BOOL
-
- handle = kernel32.OpenProcess(synchronize, False, pid)
- if not handle:
- # OpenProcess reports ERROR_INVALID_PARAMETER when the PID does not
- # exist. For access-denied and other inconclusive failures, retain
- # the PID file rather than declaring a potentially live daemon dead.
- return ctypes.get_last_error() != error_invalid_parameter
-
- try:
- wait_result = kernel32.WaitForSingleObject(handle, 0)
- # WAIT_OBJECT_0 proves the process exited. WAIT_TIMEOUT proves it
- # is live; unexpected failures are inconclusive, so retain the PID.
- return wait_result != wait_object_0
- finally:
- kernel32.CloseHandle(handle)
-
- try:
- os.kill(pid, 0)
- except ProcessLookupError:
- return False
- except PermissionError:
- return True
- return True
+ return process_alive(pid)
def _read_pid() -> int | None:
@@ -71,6 +30,7 @@ def _read_pid() -> int | None:
except (OSError, ValueError):
_PID_FILE.unlink(missing_ok=True)
return None
+ # Check if process is still running (non-destructive, cross-platform).
if not _pid_alive(pid):
_PID_FILE.unlink(missing_ok=True)
return None
@@ -168,22 +128,9 @@ def stop() -> None:
console.print("[yellow]No running server found.[/yellow]")
sys.exit(1)
- try:
- os.kill(pid, signal.SIGTERM)
- # Wait up to 10 seconds for graceful shutdown
- for _ in range(20):
- time.sleep(0.5)
- if not _pid_alive(pid):
- break
- else:
- # SIGKILL is POSIX-only. On Windows SIGTERM already maps to
- # TerminateProcess, so repeating it is the available escalation.
- try:
- os.kill(pid, getattr(signal, "SIGKILL", signal.SIGTERM))
- except OSError:
- pass
- except OSError:
- pass
+ # Graceful shutdown (SIGTERM / taskkill), escalating to a forced kill after
+ # 10s if still running. Cross-platform — no POSIX-only os.kill/SIGKILL.
+ terminate_process(pid, grace_seconds=10.0)
_PID_FILE.unlink(missing_ok=True)
console.print(f"[green]Server stopped[/green] (PID {pid}).")
diff --git a/src/openjarvis/cli/mine_cmd.py b/src/openjarvis/cli/mine_cmd.py
index 127700cd..7f6c1899 100644
--- a/src/openjarvis/cli/mine_cmd.py
+++ b/src/openjarvis/cli/mine_cmd.py
@@ -5,7 +5,6 @@ from __future__ import annotations
import asyncio
import json
import os
-import signal
import time
import urllib.error
import urllib.parse
@@ -17,6 +16,7 @@ import click
from openjarvis.core.config import HardwareInfo, detect_hardware, load_config
from openjarvis.core.registry import MinerRegistry
+from openjarvis.core.utils import process_alive, terminate_process
from openjarvis.mining._constants import (
DEFAULT_GATEWAY_METRICS_PORT,
DEFAULT_GATEWAY_RPC_PORT,
@@ -201,26 +201,11 @@ def _local_artifact_payload_and_paths(path: Path) -> tuple[dict[str, Any], set[s
def _pid_alive(pid: int | None) -> bool:
- if not pid:
- return False
- try:
- os.kill(pid, 0)
- except OSError:
- return False
- return True
+ return process_alive(pid)
def _terminate_pid(pid: int | None, *, grace_seconds: float = 3.0) -> None:
- if not pid or not _pid_alive(pid):
- return
- os.kill(pid, signal.SIGTERM)
- deadline = time.monotonic() + grace_seconds
- while time.monotonic() < deadline:
- if not _pid_alive(pid):
- return
- time.sleep(0.05)
- if _pid_alive(pid):
- os.kill(pid, signal.SIGKILL)
+ terminate_process(pid, grace_seconds=grace_seconds)
def _row(name: str, ok: bool, info: str) -> None:
diff --git a/src/openjarvis/core/__init__.py b/src/openjarvis/core/__init__.py
index 47ed8380..f10ca6cc 100644
--- a/src/openjarvis/core/__init__.py
+++ b/src/openjarvis/core/__init__.py
@@ -19,7 +19,12 @@ from openjarvis.core.types import (
ToolCall,
ToolResult,
)
-from openjarvis.core.utils import get_python_executable, open_browser
+from openjarvis.core.utils import (
+ get_python_executable,
+ open_browser,
+ process_alive,
+ terminate_process,
+)
__all__ = [
"AgentRegistry",
@@ -37,4 +42,6 @@ __all__ = [
"ToolResult",
"get_python_executable",
"open_browser",
+ "process_alive",
+ "terminate_process",
]
diff --git a/src/openjarvis/core/utils.py b/src/openjarvis/core/utils.py
index dda98e7c..9611deb6 100644
--- a/src/openjarvis/core/utils.py
+++ b/src/openjarvis/core/utils.py
@@ -6,12 +6,78 @@ from ``openjarvis.core`` must not pull in heavy modules at package init).
from __future__ import annotations
+import os
import platform
import shutil
+import signal
import subprocess
+import time
import webbrowser
+def _windows_process_alive(pid: int) -> bool:
+ """Query a Windows process handle without sending it a signal."""
+ import ctypes
+ from ctypes import wintypes
+
+ error_invalid_parameter = 87
+ synchronize = 0x00100000
+ wait_object_0 = 0x00000000
+
+ kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+ kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+ kernel32.OpenProcess.restype = wintypes.HANDLE
+ kernel32.WaitForSingleObject.argtypes = [wintypes.HANDLE, wintypes.DWORD]
+ kernel32.WaitForSingleObject.restype = wintypes.DWORD
+ kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+ kernel32.CloseHandle.restype = wintypes.BOOL
+
+ handle = kernel32.OpenProcess(synchronize, False, pid)
+ if not handle:
+ # ERROR_INVALID_PARAMETER proves that the PID does not exist. Access
+ # denied is inconclusive, so do not treat a potentially live process as
+ # dead and risk starting a duplicate daemon.
+ return ctypes.get_last_error() != error_invalid_parameter
+
+ try:
+ # WAIT_OBJECT_0 means the process handle is signaled (the process has
+ # exited). WAIT_TIMEOUT and unexpected failures are conservatively live.
+ return kernel32.WaitForSingleObject(handle, 0) != wait_object_0
+ finally:
+ kernel32.CloseHandle(handle)
+
+
+def _posix_process_state(pid: int) -> str | None:
+ """Return a POSIX process state letter, or ``None`` when unavailable."""
+ proc_root = "/proc"
+ try:
+ with open(f"{proc_root}/{pid}/stat", encoding="utf-8") as stat_file:
+ # The command name is parenthesized and may itself contain ``)``.
+ return stat_file.read().rsplit(") ", 1)[1][:1]
+ except FileNotFoundError:
+ if os.path.isdir(proc_root):
+ return "X"
+ except (IndexError, OSError):
+ pass
+
+ # macOS and other POSIX hosts do not expose /proc. ``ps`` lets us
+ # distinguish a zombie (which still responds to kill(pid, 0)) from a live
+ # process without adding a runtime dependency.
+ try:
+ result = subprocess.run(
+ ["ps", "-o", "stat=", "-p", str(pid)],
+ capture_output=True,
+ text=True,
+ check=False,
+ )
+ except OSError:
+ return None
+ state = result.stdout.strip()
+ if result.returncode != 0 or not state:
+ return "X"
+ return state[:1]
+
+
def get_python_executable() -> str:
"""Return the best ``python`` interpreter name on PATH.
@@ -49,4 +115,75 @@ def open_browser(url: str) -> None:
webbrowser.open(url)
-__all__ = ["get_python_executable", "open_browser"]
+def process_alive(pid: int | None) -> bool:
+ """Return ``True`` if a process with *pid* is currently running.
+
+ Cross-platform and *non-destructive*. The common POSIX idiom
+ ``os.kill(pid, 0)`` must NOT be used on Windows: there ``os.kill`` maps any
+ signal to ``TerminateProcess``, so a "liveness probe" would actually kill
+ the process. On Windows we inspect a process handle instead.
+ """
+ if not pid or pid <= 0:
+ return False
+ if platform.system() == "Windows":
+ return _windows_process_alive(pid)
+ try:
+ os.kill(pid, 0)
+ except ProcessLookupError:
+ return False
+ except PermissionError:
+ pass
+ except OSError:
+ return False
+
+ # A terminated child remains in the process table as a zombie until its
+ # parent reaps it. ``kill(pid, 0)`` reports that entry as present, but it can
+ # no longer execute and must not trigger force-kill waits or stale-PID reuse.
+ return _posix_process_state(pid) not in {"X", "Z"}
+
+
+def terminate_process(pid: int | None, *, grace_seconds: float = 3.0) -> None:
+ """Terminate *pid* gracefully, escalating to a forced kill (cross-platform).
+
+ POSIX sends ``SIGTERM`` then, after *grace_seconds*, ``SIGKILL``. Windows
+ has neither; it uses ``taskkill`` (graceful) then ``taskkill /F /T`` (force,
+ whole tree). ``signal.SIGKILL`` does not exist on Windows, so it is only
+ referenced inside the POSIX branch.
+ """
+ if not process_alive(pid):
+ return
+ is_windows = platform.system() == "Windows"
+
+ if is_windows:
+ subprocess.run(["taskkill", "/PID", str(pid)], capture_output=True, check=False)
+ else:
+ try:
+ os.kill(pid, signal.SIGTERM)
+ except OSError:
+ return
+
+ deadline = time.monotonic() + max(0.0, grace_seconds)
+ while time.monotonic() < deadline:
+ if not process_alive(pid):
+ return
+ time.sleep(0.05)
+
+ if is_windows:
+ subprocess.run(
+ ["taskkill", "/F", "/T", "/PID", str(pid)],
+ capture_output=True,
+ check=False,
+ )
+ else:
+ try:
+ os.kill(pid, signal.SIGKILL)
+ except OSError:
+ pass
+
+
+__all__ = [
+ "get_python_executable",
+ "open_browser",
+ "process_alive",
+ "terminate_process",
+]
diff --git a/tests/core/test_utils.py b/tests/core/test_utils.py
new file mode 100644
index 00000000..b6866677
--- /dev/null
+++ b/tests/core/test_utils.py
@@ -0,0 +1,186 @@
+"""Tests for cross-platform process helpers in ``openjarvis.core.utils``."""
+
+from __future__ import annotations
+
+import os
+import platform
+import signal
+import subprocess
+import sys
+import time
+from unittest.mock import MagicMock, call, patch
+
+import pytest
+
+from openjarvis.core.utils import (
+ _windows_process_alive,
+ process_alive,
+ terminate_process,
+)
+
+
+class TestProcessAlive:
+ def test_current_process_is_alive(self) -> None:
+ assert process_alive(os.getpid()) is True
+
+ def test_bogus_pid_not_alive(self) -> None:
+ assert process_alive(999_999_999) is False
+
+ def test_none_pid_not_alive(self) -> None:
+ assert process_alive(None) is False
+
+ def test_nonpositive_pid_not_alive(self) -> None:
+ assert process_alive(0) is False
+ assert process_alive(-1) is False
+
+ @pytest.mark.skipif(platform.system() == "Windows", reason="POSIX-only")
+ def test_unreaped_zombie_is_not_alive(self) -> None:
+ proc = subprocess.Popen([sys.executable, "-c", "pass"])
+ try:
+ for _ in range(100):
+ if not process_alive(proc.pid):
+ break
+ time.sleep(0.01)
+ assert process_alive(proc.pid) is False
+ finally:
+ proc.wait(timeout=5)
+
+ def test_permission_error_is_conservatively_alive(self) -> None:
+ with (
+ patch("openjarvis.core.utils.platform.system", return_value="Linux"),
+ patch("openjarvis.core.utils.os.kill", side_effect=PermissionError),
+ patch("openjarvis.core.utils._posix_process_state", return_value=None),
+ ):
+ assert process_alive(1234) is True
+
+ def test_windows_path_never_calls_os_kill(self) -> None:
+ with (
+ patch("openjarvis.core.utils.platform.system", return_value="Windows"),
+ patch(
+ "openjarvis.core.utils._windows_process_alive", return_value=True
+ ) as win_alive,
+ patch("openjarvis.core.utils.os.kill") as os_kill,
+ ):
+ assert process_alive(4321) is True
+ win_alive.assert_called_once_with(4321)
+ os_kill.assert_not_called()
+
+
+class TestWindowsProcessAlive:
+ @staticmethod
+ def _kernel(open_result: int, wait_result: int = 0) -> MagicMock:
+ kernel32 = MagicMock()
+ kernel32.OpenProcess.return_value = open_result
+ kernel32.WaitForSingleObject.return_value = wait_result
+ return kernel32
+
+ def test_missing_pid(self) -> None:
+ import ctypes
+
+ kernel32 = self._kernel(0)
+ with (
+ patch.object(ctypes, "WinDLL", return_value=kernel32, create=True),
+ patch.object(ctypes, "get_last_error", return_value=87, create=True),
+ ):
+ assert _windows_process_alive(1234) is False
+
+ def test_access_denied_is_conservatively_alive(self) -> None:
+ import ctypes
+
+ kernel32 = self._kernel(0)
+ with (
+ patch.object(ctypes, "WinDLL", return_value=kernel32, create=True),
+ patch.object(ctypes, "get_last_error", return_value=5, create=True),
+ ):
+ assert _windows_process_alive(1234) is True
+
+ @pytest.mark.parametrize(
+ ("wait_result", "expected"), [(0x00000000, False), (0x00000102, True)]
+ )
+ def test_process_handle_state(self, wait_result: int, expected: bool) -> None:
+ import ctypes
+
+ kernel32 = self._kernel(99, wait_result)
+ with patch.object(ctypes, "WinDLL", return_value=kernel32, create=True):
+ assert _windows_process_alive(1234) is expected
+ kernel32.CloseHandle.assert_called_once_with(99)
+
+
+class TestTerminateProcess:
+ def _spawn_sleeper(self) -> subprocess.Popen:
+ # Portable long-running child: sleeps well beyond the test's lifetime.
+ return subprocess.Popen([sys.executable, "-c", "import time; time.sleep(60)"])
+
+ def test_terminates_running_process(self) -> None:
+ proc = self._spawn_sleeper()
+ try:
+ # Give the interpreter a moment to come up.
+ for _ in range(20):
+ if process_alive(proc.pid):
+ break
+ time.sleep(0.05)
+ assert process_alive(proc.pid) is True
+
+ terminate_process(proc.pid, grace_seconds=5.0)
+
+ # Should be gone shortly after terminate returns.
+ for _ in range(20):
+ if not process_alive(proc.pid):
+ break
+ time.sleep(0.05)
+ assert process_alive(proc.pid) is False
+ finally:
+ try:
+ proc.wait(timeout=5)
+ except Exception:
+ proc.kill()
+
+ def test_terminate_bogus_pid_no_crash(self) -> None:
+ # Must be a no-op, never raise, on any platform.
+ terminate_process(999_999_999)
+
+ def test_terminate_none_no_crash(self) -> None:
+ terminate_process(None)
+
+ def test_posix_escalates_to_sigkill(self) -> None:
+ with (
+ patch("openjarvis.core.utils.platform.system", return_value="Linux"),
+ patch("openjarvis.core.utils.process_alive", return_value=True),
+ patch("openjarvis.core.utils.os.kill") as os_kill,
+ ):
+ terminate_process(1234, grace_seconds=0)
+ assert os_kill.call_args_list == [
+ call(1234, signal.SIGTERM),
+ call(1234, signal.SIGKILL),
+ ]
+
+ def test_windows_graceful_taskkill(self) -> None:
+ with (
+ patch("openjarvis.core.utils.platform.system", return_value="Windows"),
+ patch("openjarvis.core.utils.process_alive", side_effect=[True, False]),
+ patch("openjarvis.core.utils.subprocess.run") as run,
+ ):
+ terminate_process(1234, grace_seconds=1)
+ run.assert_called_once_with(
+ ["taskkill", "/PID", "1234"], capture_output=True, check=False
+ )
+
+ def test_windows_escalates_to_forced_tree_kill(self) -> None:
+ with (
+ patch("openjarvis.core.utils.platform.system", return_value="Windows"),
+ patch("openjarvis.core.utils.process_alive", return_value=True),
+ patch("openjarvis.core.utils.subprocess.run") as run,
+ ):
+ terminate_process(1234, grace_seconds=0)
+ assert run.call_args_list == [
+ call(
+ ["taskkill", "/PID", "1234"],
+ capture_output=True,
+ check=False,
+ ),
+ call(
+ ["taskkill", "/F", "/T", "/PID", "1234"],
+ capture_output=True,
+ check=False,
+ ),
+ ]