diff --git a/agent/turn_api_call.py b/agent/turn_api_call.py
index 58c0af546d..aabc740115 100644
--- a/agent/turn_api_call.py
+++ b/agent/turn_api_call.py
@@ -1,7 +1,9 @@
-"""The provider call itself for the conversation turn's retry loop: streaming decision,
-MoA prepared-request handshake, the LLM execution middleware wrapper, the redirect
-``_model_request_active`` bracket and the response-vs-redirect crossing check. Extracted
-from ``run_conversation``; nothing here imports ``agent.conversation_loop`` at module level.
+"""The provider call for the conversation turn's retry loop: ``nous_rate_limit_guard`` (skip
+the attempt while another session's Nous Portal rate limit is active), ``perform_api_call``
+(streaming decision, MoA prepared-request handshake, LLM execution middleware wrapper, the
+redirect ``_model_request_active`` bracket and the response-vs-redirect crossing check) and
+``handle_api_interrupt`` (``InterruptedError`` mid-call). Extracted from
+``run_conversation``; nothing here imports ``agent.conversation_loop`` at module level.
 """
 
 from __future__ import annotations
diff --git a/agent/turn_iteration_prep.py b/agent/turn_iteration_prep.py
index eb2f3130c3..b209e27594 100644
--- a/agent/turn_iteration_prep.py
+++ b/agent/turn_iteration_prep.py
@@ -1,9 +1,12 @@
-"""Per-iteration transcript preparation for the conversation turn loop, run before the request
-is assembled: the ``agent:step`` callback, skill-nudge counter, pre-API ``/steer`` drain into
-the newest tool result (never a user message — alternation), run-budget wrap-up notice,
-tool_call argument sanitization, legacy interrupt-scaffold ghost-row drop and role-alternation
-repair. Extracted from ``run_conversation``; nothing here imports
-``agent.conversation_loop`` at module level (cycle).
+"""Outer-iteration bookkeeping for the conversation turn loop, in call order:
+
+``begin_iteration`` (pending redirect, interrupt / review-budget / iteration-budget exits),
+``prepare_iteration`` (``agent:step`` callback, skill-nudge counter, pre-API ``/steer`` drain
+into the newest tool result — never a user message, alternation — run-budget wrap-up notice,
+tool_call argument sanitization, legacy interrupt-scaffold ghost-row drop, role-alternation
+repair), ``announce_api_call`` (verbose summary / quiet thinking spinner) and, after the retry
+loop, ``apply_retry_restarts`` (consumes the ``TurnRetryState`` restart flags). Extracted from
+``run_conversation``; nothing here imports ``agent.conversation_loop`` at module level (cycle).
 """
 
 from __future__ import annotations