docs: explain Guardian retry invariants

Co-authored-by: Codex noreply@openai.com

codex-rs/core/src/guardian/review.rs

@@ -668,6 +668,11 @@ async fn run_guardian_review(
     }
 }
 
+/// Runs one Guardian review attempt and, for transient failures, one bounded retry.
+///
+/// Availability failures wait with full jitter before retrying with the normal
+/// deadline. Model timeouts retry immediately with a shorter deadline.
+/// Cancellation stops the retry without converting it into a denial.
 async fn run_guardian_review_session_with_retry(
     session: Arc<Session>,
     turn: Arc<TurnContext>,

codex-rs/core/src/guardian/review_session.rs

@@ -911,6 +911,10 @@ fn event_matches_turn(event: &Event, expected_turn_id: &str) -> bool {
     }
 }
 
+/// Builds the locked-down config used by Guardian review sessions.
+///
+/// Provider-level retries are disabled because the Guardian retry wrapper owns
+/// the complete retry budget and must issue at most one additional review.
 pub(crate) fn build_guardian_review_session_config(
     parent_config: &Config,
     live_network_config: Option<codex_network_proxy::NetworkProxyConfig>,