Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

fix(cli): terminate launched process trees

Alishahryar1ca2cf6a6c169
diff --git a/cli/entrypoints.py b/cli/entrypoints.py
index 7c5d32a4..fe2bdffc 100644
--- a/cli/entrypoints.py
+++ b/cli/entrypoints.py
@@ -14,7 +14,12 @@ import uvicorn
from api.admin_urls import local_proxy_root_url
from api.app import GracefulLifespanApp, create_app
-from cli.process_registry import kill_all_best_effort
+from cli.process_registry import (
+ kill_all_best_effort,
+ kill_pid_tree_best_effort,
+ register_pid,
+ unregister_pid,
+)
from config.settings import Settings, get_settings
PROXY_PREFLIGHT_PATH = "/health"
@@ -147,8 +152,12 @@ def launch_claude(argv: Sequence[str] | None = None) -> None:
args = list(sys.argv[1:] if argv is None else argv)
command = [settings.claude_cli_bin, *args]
env = _claude_child_env(settings, os.environ)
+ process: subprocess.Popen[bytes] | None = None
try:
- result = subprocess.run(command, env=env, check=False)
+ process = subprocess.Popen(command, env=env)
+ if process.pid:
+ register_pid(process.pid)
+ return_code = process.wait()
except FileNotFoundError:
print(
f"Could not find Claude Code command: {settings.claude_cli_bin}",
@@ -159,5 +168,13 @@ def launch_claude(argv: Sequence[str] | None = None) -> None:
file=sys.stderr,
)
raise SystemExit(127) from None
+ except KeyboardInterrupt:
+ if process is not None and process.pid:
+ kill_pid_tree_best_effort(process.pid)
+ process.wait()
+ raise
+ finally:
+ if process is not None and process.pid:
+ unregister_pid(process.pid)
- raise SystemExit(result.returncode)
+ raise SystemExit(return_code)
diff --git a/cli/process_registry.py b/cli/process_registry.py
index 1dadda0f..c88f8a8f 100644
--- a/cli/process_registry.py
+++ b/cli/process_registry.py
@@ -9,6 +9,7 @@ from __future__ import annotations
import atexit
import os
+import signal
import subprocess
import threading
@@ -43,32 +44,35 @@ def unregister_pid(pid: int) -> None:
_pids.discard(int(pid))
+def kill_pid_tree_best_effort(pid: int) -> None:
+ """Kill a tracked process and its children where the platform supports it."""
+ if not pid:
+ return
+ if os.name == "nt":
+ try:
+ # /T kills child processes, /F forces termination.
+ subprocess.run(
+ ["taskkill", "/PID", str(pid), "/T", "/F"],
+ stdout=subprocess.DEVNULL,
+ stderr=subprocess.DEVNULL,
+ check=False,
+ )
+ except Exception as e:
+ logger.debug("process_registry: taskkill failed pid=%s: %s", pid, e)
+ return
+
+ # Best-effort fallback for non-Windows.
+ try:
+ os.kill(pid, signal.SIGTERM)
+ except Exception as e:
+ logger.debug("process_registry: terminate failed pid=%s: %s", pid, e)
+
+
def kill_all_best_effort() -> None:
"""Kill any still-running registered pids (best-effort)."""
with _lock:
pids = list(_pids)
_pids.clear()
- if not pids:
- return
-
- if os.name == "nt":
- for pid in pids:
- try:
- # /T kills child processes, /F forces termination.
- subprocess.run(
- ["taskkill", "/PID", str(pid), "/T", "/F"],
- stdout=subprocess.DEVNULL,
- stderr=subprocess.DEVNULL,
- check=False,
- )
- except Exception as e:
- logger.debug("process_registry: taskkill failed pid=%s: %s", pid, e)
- return
-
- # Best-effort fallback for non-Windows.
for pid in pids:
- try:
- os.kill(pid, 9)
- except Exception as e:
- logger.debug("process_registry: kill failed pid=%s: %s", pid, e)
+ kill_pid_tree_best_effort(pid)
diff --git a/cli/session.py b/cli/session.py
index bba070d0..a70baf48 100644
--- a/cli/session.py
+++ b/cli/session.py
@@ -11,7 +11,7 @@ from loguru import logger
from core.trace import trace_event
-from .process_registry import register_pid, unregister_pid
+from .process_registry import kill_pid_tree_best_effort, register_pid, unregister_pid
# Cap stderr capture so a runaway child cannot exhaust memory; pipe is still drained.
_MAX_STDERR_CAPTURE_BYTES = 256 * 1024
@@ -325,7 +325,7 @@ class CLISession:
if self.process and self.process.returncode is None:
try:
logger.info(f"Stopping Claude CLI process {self.process.pid}")
- self.process.terminate()
+ kill_pid_tree_best_effort(self.process.pid)
try:
await asyncio.wait_for(self.process.wait(), timeout=5.0)
except TimeoutError:
diff --git a/tests/cli/test_cli.py b/tests/cli/test_cli.py
index 590f51cd..53143316 100644
--- a/tests/cli/test_cli.py
+++ b/tests/cli/test_cli.py
@@ -390,10 +390,11 @@ class TestCLISession:
session.process = mock_process
- stopped = await session.stop()
+ with patch("cli.session.kill_pid_tree_best_effort") as kill_tree:
+ stopped = await session.stop()
assert stopped is True
- mock_process.terminate.assert_called_once()
+ kill_tree.assert_called_once_with(mock_process.pid)
mock_process.wait.assert_called()
@pytest.mark.asyncio
@@ -417,10 +418,11 @@ class TestCLISession:
session.process = mock_process
- stopped = await session.stop()
+ with patch("cli.session.kill_pid_tree_best_effort") as kill_tree:
+ stopped = await session.stop()
assert stopped is True
- mock_process.terminate.assert_called()
+ kill_tree.assert_called_once_with(mock_process.pid)
mock_process.kill.assert_called()
@pytest.mark.asyncio
@@ -591,12 +593,14 @@ class TestCLISession:
mock_process = MagicMock()
mock_process.returncode = None
- # Raise exception on terminate
- mock_process.terminate.side_effect = RuntimeError("Permission denied")
session.process = mock_process
- stopped = await session.stop()
+ with patch(
+ "cli.session.kill_pid_tree_best_effort",
+ side_effect=RuntimeError("Permission denied"),
+ ):
+ stopped = await session.stop()
assert stopped is False
diff --git a/tests/cli/test_entrypoints.py b/tests/cli/test_entrypoints.py
index c58095f7..1b420b2c 100644
--- a/tests/cli/test_entrypoints.py
+++ b/tests/cli/test_entrypoints.py
@@ -1,6 +1,5 @@
"""Tests for cli/entrypoints.py — fcc-init scaffolding logic."""
-import subprocess
import tomllib
from pathlib import Path
from types import SimpleNamespace
@@ -201,22 +200,50 @@ def test_launch_claude_passes_args_and_child_env(
with (
patch("cli.entrypoints.get_settings", return_value=settings),
patch("cli.entrypoints._preflight_proxy", return_value=None),
- patch(
- "cli.entrypoints.subprocess.run",
- return_value=subprocess.CompletedProcess(["claude-test"], 7),
- ) as run,
+ patch("cli.entrypoints.subprocess.Popen") as popen,
+ patch("cli.entrypoints.register_pid") as register_pid,
+ patch("cli.entrypoints.unregister_pid") as unregister_pid,
pytest.raises(SystemExit) as exc_info,
):
+ process = popen.return_value
+ process.pid = 12345
+ process.wait.return_value = 7
launch_claude(["--model", "sonnet"])
assert exc_info.value.code == 7
- run.assert_called_once()
- assert run.call_args.args[0] == ["claude-test", "--model", "sonnet"]
- child_env = run.call_args.kwargs["env"]
+ popen.assert_called_once()
+ assert popen.call_args.args[0] == ["claude-test", "--model", "sonnet"]
+ child_env = popen.call_args.kwargs["env"]
assert child_env["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:9191"
assert child_env["ANTHROPIC_AUTH_TOKEN"] == "proxy-token"
assert child_env["CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY"] == "1"
assert child_env["KEEP_ME"] == "yes"
+ register_pid.assert_called_once_with(12345)
+ unregister_pid.assert_called_once_with(12345)
+
+
+def test_launch_claude_keyboard_interrupt_kills_child_tree() -> None:
+ from cli.entrypoints import launch_claude
+
+ settings = _launcher_settings(port=9191, token="proxy-token")
+
+ with (
+ patch("cli.entrypoints.get_settings", return_value=settings),
+ patch("cli.entrypoints._preflight_proxy", return_value=None),
+ patch("cli.entrypoints.subprocess.Popen") as popen,
+ patch("cli.entrypoints.register_pid"),
+ patch("cli.entrypoints.kill_pid_tree_best_effort") as kill_tree,
+ patch("cli.entrypoints.unregister_pid") as unregister_pid,
+ pytest.raises(KeyboardInterrupt),
+ ):
+ process = popen.return_value
+ process.pid = 12345
+ process.wait.side_effect = [KeyboardInterrupt, 0]
+
+ launch_claude([])
+
+ kill_tree.assert_called_once_with(12345)
+ unregister_pid.assert_called_once_with(12345)
def test_launch_claude_unreachable_proxy_exits_with_hint(
diff --git a/tests/cli/test_process_registry.py b/tests/cli/test_process_registry.py
index 36032032..334046f0 100644
--- a/tests/cli/test_process_registry.py
+++ b/tests/cli/test_process_registry.py
@@ -1,4 +1,5 @@
import os
+import subprocess
from unittest.mock import patch
@@ -76,3 +77,16 @@ def test_process_registry_kill_all_best_effort_windows_noop_when_taskkill_missin
monkeypatch.setattr(subprocess, "run", _boom)
pr.kill_all_best_effort()
+
+
+def test_process_registry_kill_pid_tree_windows_uses_taskkill(monkeypatch):
+ from cli import process_registry as pr
+
+ calls = []
+ monkeypatch.setattr(os, "name", "nt", raising=False)
+ monkeypatch.setattr(subprocess, "run", lambda *a, **kw: calls.append((a, kw)))
+
+ pr.kill_pid_tree_best_effort(12345)
+
+ assert calls
+ assert calls[0][0][0] == ["taskkill", "/PID", "12345", "/T", "/F"]