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

src/beaver_gateway/conversations/distill.py

@@ -1,13 +1,8 @@
-"""Closing a deep chat: the digest, the index, the file line cap (§6.4, §8.4).
+"""Closing a deep chat: the digest, the index, the file line cap.
 
-The gateway knows no path by itself (§0.8): ``Distiller`` from ``config.py``
-names the agent, says where digests land and where the index lives, and
-the distiller writes the file on its own. What the gateway does is check that a file
-with a valid frontmatter appeared under ``Distiller.dir`` during the fork
-turn, put one line into the index, and cap the merge text at
-``SUMMARY_LINES``. ``LineCap`` is the same idea for a file a job rewrites
-(``состояние.md``): a result longer than the cap is bounced - the file
-goes back to what it was and the job is told to shorten.
+``Distiller`` says where digests and the index live; the gateway checks the
+digest's frontmatter and caps the merge text. ``LineCap`` is the same idea
+for a file a job rewrites: too long, and it is bounced back unchanged.
 """
 
 from __future__ import annotations
@@ -39,7 +34,7 @@ __all__ = [
 ]
 
 SUMMARY_LINES = 5
-"""A merge into the master is at most this many lines (§6.4)."""
+"""A merge into the master is at most this many lines."""
 
 
 @dataclass(frozen=True, slots=True)

src/beaver_gateway/conversations/injects.py

@@ -1,13 +1,8 @@
-"""Persisted per-conversation queue, ``urgent > user > wake > normal`` (§3.4).
+"""Persisted per-conversation queue: ``urgent > user > wake > normal``.
 
-One ``ClaudeSDKClient`` runs one turn at a time, so ordering has to happen
-before the client: the rows here are the queue, ``core/conversations``
-runs one worker per conversation over them. ``urgent`` cuts a running
-turn, ``user`` is the human, ``wake`` starts a turn as soon as the
-conversation is idle and takes the queued normals with it, ``normal``
-waits for the batching window or rides with the next turn. A row that is
-still ``running`` when the gateway starts was cut by a restart; it is
-flagged ``interrupted`` and never re-run.
+conversations/service.py runs one worker per conversation over these rows.
+A row still ``running`` when the gateway starts was cut by a restart and is
+flagged ``interrupted``, never re-run.
 """
 
 from __future__ import annotations

src/beaver_gateway/conversations/kinds.py

@@ -1,4 +1,4 @@
-"""Conversation kinds (§3.1) as one closed type for agents, frontends, service."""
+"""Conversation kinds as one closed type for agents, frontends, service."""
 
 from __future__ import annotations
 

src/beaver_gateway/conversations/rotation.py

@@ -1,11 +1,7 @@
-"""Master rotation (§4.5, §8.1, §8.3).
+"""Master rotation: one logical master thread, many physical sessions.
 
-One logical master thread, many physical sessions: when the policy says
-so, a new master is spawned and takes over the window atomically, the old
-one writes its handout as its last turn, closes, its finished branches get
-marked in their windows, its queued normal injects move over, and the new
-one receives "new day". Silence is measured by the user's messages only -
-injects never extend a day.
+When the policy says so, a new master takes over the window; the old one
+hands out, closes, and its branches and queued normal injects move over.
 """
 
 from __future__ import annotations

src/beaver_gateway/conversations/tools.py

@@ -1,8 +1,7 @@
-"""In-process MCP server with the gateway's own tools (§3.1, §3.2).
+"""In-process MCP server with the gateway's own tools.
 
 One server per live session so every tool knows which conversation is
-calling; ``alwaysLoad`` keeps the tools out of tool search. Which names a
-session gets comes from ``ClaudeAgent.gateway_tools``.
+calling. Which names a session gets comes from ``ClaudeAgent.gateway_tools``.
 """
 
 from __future__ import annotations
@@ -68,11 +67,10 @@ def build_tool_server(
 def _redacting(spec: SdkMcpTool[Any]) -> SdkMcpTool[Any]:
     """Put a tool's result through the same mask as every other MCP.
 
-    These tools are mounted in-process by the SDK, so they bypass the
-    ``FastMCP`` middleware in :mod:`beaver_gateway.mcp.redacting` and
-    need the filter attached here instead. ``read_conversation`` is the
-    one that earns it: it replays a transcript, and a transcript written
-    before any of this existed can still hold a credential.
+    These tools are mounted in-process, bypassing the ``FastMCP`` middleware
+    in :mod:`beaver_gateway.mcp.redacting`, so the filter is attached here
+    instead. ``read_conversation`` earns it: a replayed transcript can still
+    hold a credential written before redaction existed.
     """
     inner = spec.handler