Add real-subprocess reaper test (Linux/macOS CI coverage)

The reaper had no CI coverage at all (ci-start-server never passes an owner
pid, so the plugin-armed path never runs in CI). Close that — and the
"armed reaper only ever ran on macOS" gap — with an integration test that
spawns a real `python -m godot_ai --owner-pid` server, kills a throwaway owner
process, and asserts the server self-terminates and frees its port.

This exercises the genuine POSIX primitives (os.kill(pid,0) liveness + SIGTERM
self-shutdown → uvicorn graceful drain) on every OS pytest runs on — crucially
the ubuntu runners (Python 3.11 + 3.13), giving real Linux coverage of the
armed reaper. Skipped on Windows, where the reaper is disabled.

Adds GODOT_AI_REAPER_POLL_SECONDS so the test drives a sub-second reap instead
of waiting the production 5s; malformed/absent falls back to the default.

Passes locally on macOS (Python 3.13) in ~2s.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: dsarno

src/godot_ai/orphan_reaper.py

@@ -33,6 +33,24 @@
 logger = logging.getLogger(__name__)
 
 DEFAULT_POLL_SECONDS = 5.0
+POLL_SECONDS_ENV = "GODOT_AI_REAPER_POLL_SECONDS"
+
+
+def poll_seconds_from_env() -> float:
+    """Reaper poll interval, overridable via ``GODOT_AI_REAPER_POLL_SECONDS``.
+
+    Defaults to :data:`DEFAULT_POLL_SECONDS`. The override exists so the
+    subprocess integration test can drive a fast (<1s) reap instead of waiting
+    the production 5s; a malformed value falls back to the default.
+    """
+    raw = os.environ.get(POLL_SECONDS_ENV, "").strip()
+    if not raw:
+        return DEFAULT_POLL_SECONDS
+    try:
+        value = float(raw)
+    except ValueError:
+        return DEFAULT_POLL_SECONDS
+    return value if value > 0 else DEFAULT_POLL_SECONDS
 
 
 def should_arm_reaper(owner_pid: int | None) -> bool:

src/godot_ai/server.py

@@ -25,7 +25,7 @@
     PreserveGodotCommandErrorData,
     StripClientWrapperKwargs,
 )
-from godot_ai.orphan_reaper import should_arm_reaper, watch_owner
+from godot_ai.orphan_reaper import poll_seconds_from_env, should_arm_reaper, watch_owner
 from godot_ai.resources.editor import register_editor_resources
 from godot_ai.resources.library import register_library_resources
 from godot_ai.resources.nodes import register_node_resources
@@ -126,7 +126,11 @@ async def _lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
         reaper_task: asyncio.Task | None = None
         if should_arm_reaper(owner_pid):
             reaper_task = asyncio.create_task(
-                watch_owner(owner_pid, lambda: len(registry.list_all()))
+                watch_owner(
+                    owner_pid,
+                    lambda: len(registry.list_all()),
+                    poll_seconds=poll_seconds_from_env(),
+                )
             )
             logger.info("Orphan reaper armed for owner editor pid %d", owner_pid)
         elif owner_pid and owner_pid > 0:

tests/integration/test_orphan_reaper_subprocess.py

@@ -0,0 +1,108 @@
+"""End-to-end orphan-reaper test against a REAL server subprocess.
+
+Unlike the unit tests (which inject fakes), this spawns an actual
+``python -m godot_ai`` HTTP server with ``--owner-pid`` pointed at a throwaway
+owner process, kills the owner, and asserts the server self-terminates. It
+exercises the genuine POSIX primitives — ``os.kill(pid, 0)`` liveness and the
+``SIGTERM``-to-self → uvicorn graceful shutdown — on whatever OS CI runs it on
+(notably the Linux runners, which the in-CI plugin path never arms the reaper
+on). Skipped on Windows, where the reaper is intentionally disabled.
+"""
+
+from __future__ import annotations
+
+import os
+import socket
+import subprocess
+import sys
+import time
+
+import pytest
+
+pytestmark = pytest.mark.skipif(
+    sys.platform.startswith("win"),
+    reason="orphan reaper is disabled on Windows (see should_arm_reaper)",
+)
+
+
+def _free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+def _port_open(port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.settimeout(0.25)
+        return s.connect_ex(("127.0.0.1", port)) == 0
+
+
+def _terminate(proc: subprocess.Popen | None) -> None:
+    if proc is None or proc.poll() is not None:
+        return
+    proc.kill()
+    try:
+        proc.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        pass
+
+
+def test_server_subprocess_reaps_when_owner_dies():
+    http_port = _free_port()
+    ws_port = _free_port()
+
+    env = dict(os.environ)
+    env["GODOT_AI_DISABLE_TELEMETRY"] = "true"
+    env["GODOT_AI_REAPER_POLL_SECONDS"] = "0.3"  # fast reap for the test
+
+    owner = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(300)"])
+    server = None
+    try:
+        server = subprocess.Popen(
+            [
+                sys.executable,
+                "-m",
+                "godot_ai",
+                "--transport",
+                "streamable-http",
+                "--port",
+                str(http_port),
+                "--ws-port",
+                str(ws_port),
+                "--owner-pid",
+                str(owner.pid),
+            ],
+            env=env,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+
+        # Wait for the HTTP listener to come up (server fully started).
+        deadline = time.monotonic() + 20
+        while time.monotonic() < deadline:
+            if server.poll() is not None:
+                pytest.fail(f"server exited early with code {server.returncode}")
+            if _port_open(http_port):
+                break
+            time.sleep(0.2)
+        else:
+            pytest.fail("server did not start listening within 20s")
+
+        # Owner alive + no editor sessions → reaper must NOT fire yet.
+        time.sleep(1.0)
+        assert server.poll() is None, "server reaped while owner still alive"
+
+        # Kill the owner → reaper should see it gone, 0 sessions, and shut down.
+        owner.kill()
+        owner.wait(timeout=5)
+
+        try:
+            rc = server.wait(timeout=15)
+        except subprocess.TimeoutExpired:
+            pytest.fail("server did NOT self-terminate after owner died (reaper failed)")
+        assert rc is not None
+        # Port released after the process exits.
+        assert not _port_open(http_port)
+    finally:
+        _terminate(server)
+        _terminate(owner)