From 2ebde10db2d344fa17338e85f366a454c4dfb718 Mon Sep 17 00:00:00 2001
From: Charles Cunningham <ccunningham@openai.com>
Date: Sat, 31 Jan 2026 12:58:53 -0800
Subject: [PATCH] Document turn context placeholders

---
 codex-rs/core/src/state/session.rs | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/codex-rs/core/src/state/session.rs b/codex-rs/core/src/state/session.rs
index b8080848a9..12ccf6996b 100644
--- a/codex-rs/core/src/state/session.rs
+++ b/codex-rs/core/src/state/session.rs
@@ -60,6 +60,10 @@ impl SessionState {
         self.history.record_items(items, policy);
     }
 
+    /// Keep `turn_context_history` aligned with user turns even when no TurnContextItem exists
+    /// yet (e.g., legacy rollouts or model-sourced user messages). We push a `None` placeholder
+    /// for each user message so later rollback/backtrack logic can safely index the latest
+    /// user turn and optionally fill the slot with a TurnContextItem.
     pub(crate) fn record_user_turn_placeholders(&mut self, items: &[ResponseItem]) {
         for item in items {
             if matches!(item, ResponseItem::Message { role, .. } if role == "user") {