diff --git a/codex-rs/core/src/codex.rs b/codex-rs/core/src/codex.rs
index 18f1d2d2fd..8adc2b3858 100644
--- a/codex-rs/core/src/codex.rs
+++ b/codex-rs/core/src/codex.rs
@@ -1058,9 +1058,10 @@ impl Session {
         if let Ok(mut state) = self.state.try_lock() {
             if let Ok(mut active) = self.active_turn.try_lock()
                 && let Some(at) = active.as_mut()
-                    && let Ok(mut ts) = at.turn_state.try_lock() {
-                        ts.clear_pending();
-                    }
+                && let Ok(mut ts) = at.turn_state.try_lock()
+            {
+                ts.clear_pending();
+            }
             if let Some(task) = state.current_task.take() {
                 task.abort(TurnAbortReason::Interrupted);
             }
diff --git a/codex-rs/core/src/state/mod.rs b/codex-rs/core/src/state/mod.rs
index 504ada6e8d..7b1306efdd 100644
--- a/codex-rs/core/src/state/mod.rs
+++ b/codex-rs/core/src/state/mod.rs
@@ -1,8 +1,14 @@
-//! Session/turn state module scaffolding.
+//! Session/turn state module.
 //!
-//! This module will encapsulate all mutable state for a Codex session.
-//! It starts with lightweight placeholders to enable incremental refactors
-//! without changing behaviour.
+//! Encapsulates all mutable state for a Codex session and the currently active
+//! turn. The goal is to present lock-safe, narrow APIs so other modules never
+//! need to poke at raw mutexes or internal fields.
+//!
+//! Locking guidelines
+//! - Lock ordering: `SessionState` → `ActiveTurn` → `TurnState`.
+//! - Never hold a lock across an `.await`. Extract minimal data and drop the
+//!   guard before awaiting.
+//! - Prefer helper methods on these types rather than exposing fields.
 
 mod session;
 mod turn;