fix: ensure brain thread stops cleanly on shutdown

Author: tmcarmichael

src/brain/runner/lifecycle.py

@@ -373,6 +373,9 @@ def _stopped() -> bool:
             if state.mana_current == 0:
                 brain_log.info("[LIFECYCLE] Warmup: mana reads 0, retrying CHARINFO...")
                 for _retry in range(5):
+                    if _stopped():
+                        brain_log.info("[LIFECYCLE] Warmup mana retry interrupted by stop_event")
+                        return
                     time.sleep(1.0)
                     state = self._runner._reader.read_state(include_spawns=True)
                     if state.mana_current > 0:

src/brain/runner/loop.py

@@ -271,7 +271,7 @@ def _run_setup(self) -> None:
         self._init_monitoring()
 
         tick_rate = self._config["general"].get("tick_rate_hz", 10)
-        self._clock = TickClock(tick_rate)
+        self._clock = TickClock(tick_rate, stop_event=self._stop_event)
         self._next_snapshot = time.time() + 30.0
         self._next_tuning_eval = time.time() + 1800.0
 

src/runtime/orchestrator.py

@@ -485,24 +485,34 @@ def stop_agent(self) -> dict:
         if not self.agent_running:
             return {"error": "Not running"}
         self.stop_event.set()
-        orphaned = False
         if self.agent_thread:
+            # First wait: cooperative shutdown via stop_event (should be fast
+            # now that TickClock and warmup sleeps are interruptible).
             self.agent_thread.join(timeout=10)
             if self.agent_thread.is_alive():
-                log.warning(
-                    "[LIFECYCLE] stop_agent: brain thread did not stop within 10s -- it will be orphaned"
+                log.warning("[LIFECYCLE] stop_agent: brain thread did not stop within 10s -- waiting longer")
+                # Second wait: allow cleanup callbacks (file I/O) to finish.
+                self.agent_thread.join(timeout=20)
+            if self.agent_thread.is_alive():
+                # Thread is truly stuck (hung syscall, deadlock).  Keep the
+                # reference so start_agent() still refuses to create a
+                # duplicate runner -- the daemon flag ensures it dies at
+                # process exit.
+                log.error(
+                    "[LIFECYCLE] stop_agent: brain thread stuck after 30s -- "
+                    "thread kept alive (daemon); start_agent will block until it exits"
                 )
-                orphaned = True
-            else:
-                self.agent_thread = None
+                with self._agent_lock:
+                    self.agent_running = False
+                    defeats = self.agent_defeats
+                self.add_log(f"Agent stopped -- {defeats} defeats (thread stuck, will block next start)")
+                return {"running": False, "defeats": defeats, "stuck_thread": True}
+            self.agent_thread = None
         with self._agent_lock:
             self.agent_running = False
             defeats = self.agent_defeats
-        self.add_log(f"Agent stopped -- {defeats} defeats" + (" (thread orphaned)" if orphaned else ""))
-        result: dict = {"running": False, "defeats": defeats}
-        if orphaned:
-            result["orphaned_thread"] = True
-        return result
+        self.add_log(f"Agent stopped -- {defeats} defeats")
+        return {"running": False, "defeats": defeats}
 
     def pause_agent(self) -> dict:
         with self._agent_lock:

src/util/clock.py

@@ -1,24 +1,36 @@
 """Tick timing and dt tracking."""
 
+from __future__ import annotations
+
+import threading
 import time
 
 
 class TickClock:
     """Regulates the main loop to a target tick rate and tracks delta time."""
 
-    def __init__(self, tick_rate_hz: float = 10.0) -> None:
+    def __init__(self, tick_rate_hz: float = 10.0, stop_event: threading.Event | None = None) -> None:
         self._interval = 1.0 / tick_rate_hz
         self._last_tick = time.perf_counter()
         self.dt: float = 0.0
         self.tick_count: int = 0
+        self._stop_event = stop_event
 
     def wait_for_next_tick(self) -> float:
-        """Sleep until the next tick is due. Returns dt since last tick."""
+        """Sleep until the next tick is due.  Returns dt since last tick.
+
+        If a *stop_event* was provided at construction, the sleep is
+        interruptible: ``stop_event.wait(timeout)`` is used instead of
+        ``time.sleep`` so the thread wakes immediately on shutdown.
+        """
         now = time.perf_counter()
         elapsed = now - self._last_tick
         sleep_time = self._interval - elapsed
         if sleep_time > 0:
-            time.sleep(sleep_time)
+            if self._stop_event is not None:
+                self._stop_event.wait(sleep_time)
+            else:
+                time.sleep(sleep_time)
 
         now = time.perf_counter()
         self.dt = now - self._last_tick

tests/test_clock.py

@@ -2,6 +2,9 @@
 
 from __future__ import annotations
 
+import threading
+import time
+
 from util.clock import TickClock
 
 
@@ -39,3 +42,16 @@ def test_returns_dt(self) -> None:
         result = c.wait_for_next_tick()
         assert isinstance(result, float)
         assert result == c.dt
+
+    def test_stop_event_interrupts_sleep(self) -> None:
+        """A slow clock (1 Hz = 1s sleep) should return almost immediately when stop_event fires."""
+        stop = threading.Event()
+        c = TickClock(tick_rate_hz=1.0, stop_event=stop)
+        c.wait_for_next_tick()  # first tick, sets _last_tick
+
+        # Fire stop_event after 50ms -- wait_for_next_tick should unblock well before 1s
+        threading.Timer(0.05, stop.set).start()
+        t0 = time.perf_counter()
+        c.wait_for_next_tick()
+        elapsed = time.perf_counter() - t0
+        assert elapsed < 0.3, f"expected fast wakeup, took {elapsed:.3f}s"