refactor: no comments left - one-line module docstrings, contracts on public fields only; jobs/job.py; example config and README

src/beaver_gateway/backends/sessions.py

@@ -1,13 +1,9 @@
-"""Pool of live Agent SDK sessions across every Claude agent (§3.2).
+"""Pool of live Agent SDK sessions across every Claude agent.
 
-One :class:`Session` is one ``ClaudeSDKClient`` (one claude subprocess).
-The pool owns the two decisions the adapters used to make on their own:
-when a session is closed for idleness (TTL by conversation kind) and
-which one goes when memory runs out (measured RSS of the subprocess tree
-against the cgroup limit, ``max_live`` where there is no limit). Eviction
-only ever picks ``idle && !running_turn && !pending_question`` sessions
-that are neither pinned (the master) nor ``dirty`` (mirror gap not yet
-repaired); forks and jobs go first.
+One :class:`Session` is one ``ClaudeSDKClient`` (one claude subprocess). The
+pool decides when a session is closed for idleness (TTL by conversation
+kind) and which one goes when memory runs out (RSS of the subprocess tree
+against the cgroup limit, or ``max_live`` with no limit).
 """
 
 from __future__ import annotations
@@ -69,7 +65,7 @@ class Session:
     created_at: float = field(default_factory=time.monotonic)
     turns: int = 0
     state: dict[str, Any] = field(default_factory=dict)
-    """Scratch for policy rules (``core/policy``); dies with the process."""
+    """Scratch for policy rules (``agents/policy.py``); dies with the process."""
 
     @property
     def busy(self) -> bool:
@@ -77,6 +73,10 @@ class Session:
 
     @property
     def evictable(self) -> bool:
+        """Never evict a pinned (master) session or a ``dirty`` one.
+
+        ``dirty`` means a mirror gap not yet repaired.
+        """
         return not (self.pinned or self.dirty or self.busy or self.pending_question)
 
     @property
@@ -167,6 +167,7 @@ class SessionPool:
         return len(self._sessions) >= self._max_live
 
     def victims(self) -> list[Session]:
+        """Evictable sessions, forks/jobs first, then oldest idle."""
         candidates = [s for s in self._sessions.values() if s.evictable]
         candidates.sort(key=lambda s: (_EVICT_ORDER.get(s.kind, 1), s.last_used))
         return candidates