chore: document intentional await-holding cases (#18423)

## Why

This PR prepares the stack to enable Clippy await-holding lints that
were left disabled in #18178. The mechanical lock-scope cleanup is
handled separately; this PR is the documentation/configuration layer for
the remaining await-across-guard sites.

Without explicit annotations, reviewers and future maintainers cannot
tell whether an await-holding warning is a real concurrency smell or an
intentional serialization boundary.

## What changed

- Configures `clippy.toml` so `await_holding_invalid_type` also covers
`tokio::sync::{MutexGuard,RwLockReadGuard,RwLockWriteGuard}`.
- Adds targeted `#[expect(clippy::await_holding_invalid_type, reason =
...)]` annotations for intentional async guard lifetimes.
- Documents the main categories of intentional cases: active-turn state
transitions that must remain atomic, session-owned MCP manager accesses,
remote-control websocket serialization, JS REPL kernel/process
serialization, OAuth persistence, external bearer token refresh
serialization, and tests that intentionally serialize shared global or
session-owned state.
- For external bearer token refresh, documents the existing
serialization boundary: holding `cached_token` across the provider
command prevents concurrent cache misses from starting duplicate refresh
commands, and the current behavior is small enough that an explicit
expectation is easier to maintain than adding another synchronization
primitive.

## Verification

- `cargo clippy -p codex-login --all-targets`
- `cargo clippy -p codex-connectors --all-targets`
- `cargo clippy -p codex-core --all-targets`
- The follow-up PR #18698 enables `await_holding_invalid_type` and
`await_holding_lock` as workspace `deny` lints, so any undocumented
remaining offender will fail Clippy.

---
[//]: # (BEGIN SAPLING FOOTER)
Stack created with [Sapling](https://sapling-scm.com). Best reviewed
with [ReviewStack](https://reviewstack.dev/openai/codex/pull/18423).
* #18698
* __->__ #18423

codex-rs/core/src/tools/code_mode/mod.rs

@@ -259,6 +259,10 @@ pub(super) async fn build_enabled_tools(
     collect_code_mode_tool_definitions(&specs)
 }
 
+#[expect(
+    clippy::await_holding_invalid_type,
+    reason = "nested tool router construction reads through the session-owned manager guard"
+)]
 async fn build_nested_router(exec: &ExecContext) -> ToolRouter {
     let nested_tools_config = exec.turn.tools_config.for_code_mode_nested_tools();
     let listed_mcp_tools = exec

codex-rs/core/src/tools/handlers/dynamic.rs

@@ -71,6 +71,10 @@ impl ToolHandler for DynamicToolHandler {
     }
 }
 
+#[expect(
+    clippy::await_holding_invalid_type,
+    reason = "active turn checks and dynamic tool response registration must remain atomic"
+)]
 async fn request_dynamic_tool(
     session: &Session,
     turn_context: &TurnContext,

codex-rs/core/src/tools/handlers/mcp_resource.rs

@@ -240,6 +240,10 @@ impl ToolHandler for McpResourceHandler {
     }
 }
 
+#[expect(
+    clippy::await_holding_invalid_type,
+    reason = "MCP resource listing reads through the session-owned manager guard"
+)]
 async fn handle_list_resources(
     session: Arc<Session>,
     turn: Arc<TurnContext>,
@@ -344,6 +348,10 @@ async fn handle_list_resources(
     }
 }
 
+#[expect(
+    clippy::await_holding_invalid_type,
+    reason = "MCP resource template listing reads through the session-owned manager guard"
+)]
 async fn handle_list_resource_templates(
     session: Arc<Session>,
     turn: Arc<TurnContext>,

codex-rs/core/src/tools/handlers/tool_suggest.rs

@@ -34,6 +34,10 @@ impl ToolHandler for ToolSuggestHandler {
         ToolKind::Function
     }
 
+    #[expect(
+        clippy::await_holding_invalid_type,
+        reason = "tool suggestion discovery reads through the session-owned manager guard"
+    )]
     async fn handle(&self, invocation: ToolInvocation) -> Result<Self::Output, FunctionCallError> {
         let ToolInvocation {
             payload,
@@ -193,6 +197,10 @@ async fn verify_tool_suggestion_completed(
     }
 }
 
+#[expect(
+    clippy::await_holding_invalid_type,
+    reason = "connector cache refresh reads through the session-owned manager guard"
+)]
 async fn refresh_missing_suggested_connectors(
     session: &crate::session::session::Session,
     turn: &crate::session::turn_context::TurnContext,

codex-rs/core/src/tools/js_repl/mod.rs

@@ -849,6 +849,10 @@ impl JsReplManager {
             .await
     }
 
+    #[expect(
+        clippy::await_holding_invalid_type,
+        reason = "js_repl kernel initialization must be serialized with kernel state"
+    )]
     pub async fn execute_with_cancellation(
         &self,
         session: Arc<Session>,
@@ -1177,6 +1181,10 @@ impl JsReplManager {
         Ok(kernel_path)
     }
 
+    #[expect(
+        clippy::await_holding_invalid_type,
+        reason = "js_repl stdin writes must be serialized per kernel"
+    )]
     async fn write_message(
         stdin: &Arc<Mutex<ChildStdin>>,
         msg: &HostToKernel,
@@ -1224,6 +1232,10 @@ impl JsReplManager {
         }
     }
 
+    #[expect(
+        clippy::await_holding_invalid_type,
+        reason = "js_repl child shutdown must serialize process inspection and termination"
+    )]
     async fn kill_kernel_child(child: &Arc<Mutex<Child>>, reason: &'static str) {
         let mut guard = child.lock().await;
         let pid = guard.id();
@@ -1547,6 +1559,10 @@ impl JsReplManager {
         }
     }
 
+    #[expect(
+        clippy::await_holding_invalid_type,
+        reason = "nested js_repl tool routing reads through the session-owned manager guard"
+    )]
     async fn run_tool_request(exec: ExecContext, req: RunToolRequest) -> RunToolResult {
         if is_js_repl_internal_tool(&req.tool_name) {
             let error = "js_repl cannot invoke itself".to_string();

codex-rs/core/src/tools/registry.rs

@@ -239,6 +239,10 @@ impl ToolRegistry {
     //     }
     // }
 
+    #[expect(
+        clippy::await_holding_invalid_type,
+        reason = "tool dispatch must keep active-turn accounting atomic"
+    )]
     pub(crate) async fn dispatch_any(
         &self,
         invocation: ToolInvocation,

codex-rs/core/src/tools/router_tests.rs

@@ -15,6 +15,10 @@ use super::ToolRouter;
 use super::ToolRouterParams;
 
 #[tokio::test]
+#[expect(
+    clippy::await_holding_invalid_type,
+    reason = "test builds a router from session-owned MCP manager state"
+)]
 async fn js_repl_tools_only_blocks_direct_tool_calls() -> anyhow::Result<()> {
     let (session, mut turn) = make_session_and_context().await;
     turn.tools_config.js_repl_tools_only = true;
@@ -70,6 +74,10 @@ async fn js_repl_tools_only_blocks_direct_tool_calls() -> anyhow::Result<()> {
 }
 
 #[tokio::test]
+#[expect(
+    clippy::await_holding_invalid_type,
+    reason = "test builds a router from session-owned MCP manager state"
+)]
 async fn js_repl_tools_only_allows_js_repl_source_calls() -> anyhow::Result<()> {
     let (session, mut turn) = make_session_and_context().await;
     turn.tools_config.js_repl_tools_only = true;
@@ -175,6 +183,10 @@ async fn js_repl_tools_only_blocks_namespaced_js_repl_tool() -> anyhow::Result<(
 }
 
 #[tokio::test]
+#[expect(
+    clippy::await_holding_invalid_type,
+    reason = "test builds a router from session-owned MCP manager state"
+)]
 async fn parallel_support_does_not_match_namespaced_local_tool_names() -> anyhow::Result<()> {
     let (session, turn) = make_session_and_context().await;
     let mcp_tools = session